Emulator
12519
Comment: drop the legacy instructions, which just obfuscate the needed information
|
← Revision 67 as of 2016-04-15 03:17:10 ⇥
11757
|
Deletions are marked like this. | Additions are marked like this. |
Line 5: | Line 5: |
== Minimal requirements for the emulator == | == Minimal System requirements for the emulator == |
Line 13: | Line 13: |
=== /!\ If you are on amd64 === A word of warning though: if you are on amd64, take care if you uninstall the emulator and run apt-get autoremove to automatically clean the dependencies, this will break your system. Issue was fixed with android-emulator 20131120-0225-0ubuntu2, but you could still have the issue (in case you installed a previous version of the emulator, so check if you have libc6-amd64 installed in your system). If that happens to you: From still running system, initramfs / break-bottom, or elsehow: {{{ /lib/x86_64-linux-gnu/ld-2.18.so /bin/ln -s /lib/x86_64-linux-gnu/ld-2.18.so /lib64/ld-linux-x86-64.so.2 }}} Alternatively you can do: 1. reboot and eventually press shift to get to grub 1. press e to edit your command line 1. on the line "linux <…>", remove "quiet splash" and replace with break=bottom 1. press F10 or Ctrl-x to start, you will be dropped in the initramfs busybox 1. mkdir /mnt 1. you need to know your FS layout and mount /dev/<your root partition> in /mnt 1. cd /mnt/lib64/ && rm ld-linux-x86-64.so.2 && ln -s ../lib/x86_64-linux-gnu/ld-2.17.so ld-linux-x86-64.so.2 1. reboot |
|
Line 37: | Line 15: |
* Install the ubuntu-emulator package in Trusty * Create an instance |
* Install the ubuntu-emulator package * Create an instance (and/or select the desired arch to use) |
Line 42: | Line 20: |
sudo apt-get install ubuntu-emulator sudo ubuntu-emulator create myinstance |
sudo apt install ubuntu-emulator sudo ubuntu-emulator create myinstance (you can use any name for "myinstance") |
Line 47: | Line 25: |
To create a X86 instance, just give ''--arch=i386'' to ''ubuntu-emulator create'': {{{ sudo ubuntu-emulator create --arch=i386 myinstance ubuntu-emulator run myinstance }}} |
|
Line 49: | Line 33: |
* By default the latest built image from devel-proposed channel is used. This can be changed during creation with the --channel and --revision options. |
* By default, the latest built image from devel channel is used. This can be changed during creation with the following parameters: {{{ --channel, --revision }}} See [[http://developer.ubuntu.com/start/ubuntu-for-devices/image-channels]] for more details. |
Line 57: | Line 45: |
* If `ubuntu-emulator run` fails with `libGL error: Couldn't dlopen libudev.so.1 or libudev.so.0, driver detection may be broken` on amd64, this is bug:1291333. You can work around this by doing `sudo apt install libudev1:i386` * If 'ubuntu-emulator create' fails with "qemu-img: Invalid options for file format 'qcow2'", you may need to use a raw disk as per [[https://lists.launchpad.net/ubuntu-phone/msg08072.html]] {{{ --use-raw-disk }}} * The new emulator instance is created with the phablet user password set to: '''0000'''. Passwords entered on the initial wizard security screen will be ignored. A new option has been added to the latest version of ubuntu-emulator in vivid: ''--password='' which can be used to override the default password. |
|
Line 60: | Line 54: |
Until system-image works in the emulator, you can do the following to rebuild the image using the cached ubuntu-rootfs.tar.xz:{{{ $ cd ~/emulator/ $ ./build-emulator-sdcard.sh }}} To update the image to the newest version of ubuntu-rootfs.tar.xz:{{{ $ cd ~/emulator/ $ rm -f ./out/target/product/generic/ubuntu-rootfs.tar.xz $ ./build-emulator-sdcard.sh |
Until system-image works in the emulator, you can do the following to rebuild the image using the cached image:{{{ $ sudo ubuntu-emulator create myoldinstance |
Line 73: | Line 60: |
To build {{{ $ sudo apt-get install phablet-tools git bzr |
The Ubuntu emulator is composed of two parts: the runtime (what gets the emulator running) and the manager (the set of commands to start/stop and manage emulator instances). To build the runtime: {{{ $ sudo apt install phablet-tools git bzr |
Line 78: | Line 68: |
$ sudo apt-get build-dep android | $ sudo apt build-dep android |
Line 81: | Line 71: |
$ sudo apt-get install libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 zlib1g-dev:i386 | $ sudo apt install libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 zlib1g-dev:i386 |
Line 84: | Line 74: |
$ sudo apt-get install schedtool openjdk-6-jdk g++-multilib bison flex | $ sudo apt install schedtool openjdk-8-jdk g++-multilib bison flex |
Line 93: | Line 83: |
$ lunch cm_goldfish-eng $ mka }}} To generate sdcard with the ubuntu rootfs {{{ $ ./build/tools/build-emulator-sdcard.sh }}} Launch the emulator with the run-emulator script: {{{ $ ./build/tools/run-emulator.sh }}} You can also launch the emulator using your own arguments and options: {{{ $ emulator -verbose -gpu on -system $OUT/system.img -memory 512 -show-kernel -shell -no-jni -qemu -cpu cortex-a8 }}} As of 2013/11/05 there is a bug in the goldfish kernel wrt !AppArmor, so you may want to launch with !AppArmor disabled until this issue is resolved: {{{ $ emulator -verbose -gpu on -system $OUT/system.img -memory 512 -show-kernel -shell -no-jni -qemu -cpu cortex-a8 -append 'apparmor=0' |
$ lunch aosp_arm-userdebug # or aosp_x86-userdebug for the x86 emulator $ make -j<n> }}} * '''Note''': If you're using Ubuntu Trusty (14.04) as your host, make sure you don't have the package ''gcc-i686-linux-android'' installed in your system. This toolchain has a bug that breaks the emulator init system, and you should either use the Android pre-build one (by removing the package), or downloading the latest ''gcc-i686-linux-android'' from Ubuntu Utopic (14.10). To use the '''system.img''' that you just created, create an instance with ''ubuntu-emulator create --use-raw-disk'' and replace the ''system.img'' file available in the generated ''sdcard.img'' file (under ''~/.local/share/ubuntu-emulator/<my instance>'': {{{ $ simg2img out/target/product/generic_x86/system.img out/target/product/generic_x86/system.raw $ sudo mount ~/.local/share/ubuntu-emulator/myinstance/sdcard.img /tmp/mount1 $ sudo mount /tmp/mount1/system.img /tmp/mount2 $ sudo cp out/target/product/generic_x86/system.raw /tmp/mount2/var/lib/lxc/android/system.img $ sudo umount /tmp/mount2 $ sudo umount /tmp/mount1 }}} To build the manager: {{{ sudo apt install golang-go export GOPATH=$HOME/go mkdir $GOPATH export PATH=$PATH:$GOPATH/bin go get launchpad.net/goget-ubuntu-touch/ubuntu-emulator |
Line 127: | Line 119: |
= Support Status = Please check [[/Support|Support status]] to better know what is the current state of the emulator. |
|
Line 129: | Line 125: |
After starting the emulator with the wrapper script following should be available: | After starting the emulator with the wrapper script, the following should be available: |
Line 132: | Line 128: |
Emulator will appear in the output of $ adb devices, and will, once fully booted allow | Emulator will appear in the output of $ adb devices, and will, once fully booted, allow |
Line 137: | Line 133: |
* Serial console The terminal will start an Ubuntu console by default, which can be used as any virtual console. Just be aware that hiiting Control + C will stop the emulator. |
|
Line 149: | Line 142: |
Once launched graphical window title will show a port number, e.g. 5554. Connect to that over telnet, to send hardware events to the emulator | Once launched, the graphical window title will show a port number, e.g. 5554. Connect to that over telnet to send hardware events to the emulator |
Line 180: | Line 173: |
* Accessing your host device from the emulator: You can access your host machine by using the IP ''10.0.2.2'' from inside the emulator. During development you can either use that to ssh your host, or access any other service running in your host machine, such as a web server. |
|
Line 194: | Line 190: |
Being able to create a snapshot and roll back to it is very useful for developers. Eg, developers can * develop features, etc on the image, then package them up, roll back the image and test on a pristine image * save time on system-image upgrade testing * do multiple test runs, reverting to the pristine image between runs to cut down on variances * verify bugs in the image easily * etc |
|
Line 236: | Line 239: |
=== Legacy instructions === Since 20131126-0210-0ubuntu1, the run-emulator.sh script also supports disk snapshots. Being able to create a snapshot and roll back to it is very useful for developers. Eg, developers can * develop features, etc on the image, then package them up, roll back the image and test on a pristine image * save time on system-image upgrade testing * do multiple test runs, reverting to the pristine image between runs to cut down on variances * verify bugs in the image easily * etc Snapshotting can be complicated, but most of the time you just want to have a pristine snapshot that you can rollback to with the option of committing changes. Run emulator usage: {{{ $ ./run-emulator.sh help Usage: run-emulator.sh run-emulator.sh [COMMAND] Commands: use-disk-snapshots Convert images to qcow2 and create 'pristine' snapshot convert-disk DISK Convert DISK to qcow2 and create 'pristine' snapshot snapshot-disks Update 'pristine' snapshot to current state revert-disks Revert current images to 'pristine' snapshot info-disks Show disk information for current images Without arguments, run the emulated image. Note: these commands only manipulate the qemu qcow2 disk images and are unrelated to the -snapshot* and -no-snapshot* emulator command line options }}} Basic workflow: {{{ $ ./build-emulator-sdcard.sh # create image like normal, skip if already have image $ ./run-emulator.sh use-disk-snapshots $ ./run-emulator.sh <do work> $ ./run-emulator.sh revert-disks $ ./run-emulator.sh <perform tests in pristine environment> $ ./run-emulator.sh revert-disks }}} If need to rebuild the image after using snapshots:{{{ $ for i in system.img userdata.img cache.img ; do cp -f /usr/share/android/emulator/out/target/product/generic/$i out/target/product/generic/ ; done $ ./build-emulator-sdcard.sh }}} |
|
Line 297: | Line 250: |
* Powerd is disabled by default as suspending & resuming corrupts the root filesystem. * A few other services might also be disabled by default until everything is working properly with the emulator. Please check '''build-emulator-sdcard.sh''' to see the extra customization done for the emulator image. |
|
Line 302: | Line 253: |
* For running the emulator in a VM guest (e.g. Ubuntu in VMware Player) a VT-d enabled processor is needed and the proper option for supporting nested virtualization must be set in the hypervisor (e.g. in VMware Player the "Virtualize Intel VT-x/EPT or AMD-V/RVI" Option must be set). |
Table of Contents |
Getting the emulator
Minimal System requirements for the emulator
- 512MB of RAM dedicated for the emulator
- 4GB of disk space
- OpenGL capable desktop drivers (due the OpenGLES 2.0 translator)
Installing the pre-built emulator
Instructions
- Install the ubuntu-emulator package
- Create an instance (and/or select the desired arch to use)
- Run the emulator
sudo apt install ubuntu-emulator sudo ubuntu-emulator create myinstance (you can use any name for "myinstance") ubuntu-emulator run myinstance
To create a X86 instance, just give --arch=i386 to ubuntu-emulator create:
sudo ubuntu-emulator create --arch=i386 myinstance ubuntu-emulator run myinstance
Notes
- By default, the latest built image from devel channel is used.
- This can be changed during creation with the following parameters:
--channel, --revision
See http://developer.ubuntu.com/start/ubuntu-for-devices/image-channels for more details.
- This can be changed during creation with the following parameters:
- XDG_CACHE_DIR/ubuntuimage is used to download images; it is shared with ubuntu-device-flash.
- Images are stored in XDG_DATA_DIR/ubuntu-emulator.
- To update to a latest image; it is safe to create over the previous instance (upgrade option comming soon).
- Once migrated to this ubuntu-emulator-images and android-emulator can be safely removed.
- All references to run-emulator.sh and build-emulator-sdcard.sh do no apply anymore.
- Snapshotting is taken care of with the snapshot subcommand from ubuntu-emulator.
If ubuntu-emulator run fails with libGL error: Couldn't dlopen libudev.so.1 or libudev.so.0, driver detection may be broken on amd64, this is bug:1291333. You can work around this by doing sudo apt install libudev1:i386
If 'ubuntu-emulator create' fails with "qemu-img: Invalid options for file format 'qcow2'", you may need to use a raw disk as per https://lists.launchpad.net/ubuntu-phone/msg08072.html
--use-raw-disk
The new emulator instance is created with the phablet user password set to: 0000. Passwords entered on the initial wizard security screen will be ignored. A new option has been added to the latest version of ubuntu-emulator in vivid: --password= which can be used to override the default password.
Maintenance
Until system-image works in the emulator, you can do the following to rebuild the image using the cached image:
$ sudo ubuntu-emulator create myoldinstance
Building from scratch
The Ubuntu emulator is composed of two parts: the runtime (what gets the emulator running) and the manager (the set of commands to start/stop and manage emulator instances).
To build the runtime:
$ sudo apt install phablet-tools git bzr $ # install android build-dependencies $ sudo apt build-dep android $ # if we're on amd64, we need to pull in certain 32-bit packages explicitly $ sudo apt install libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 zlib1g-dev:i386 $ # this here is only needed if you didn't follow https://wiki.ubuntu.com/Touch/Porting before $ sudo apt install schedtool openjdk-8-jdk g++-multilib bison flex $ # and then work around the fact that libgl1-mesa-dev isn't Multi-Arch: same yet $ sudo ln -s /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1 /usr/lib/x86_64-linux-gnu/libGL.so $ mkdir -p emulator/ $ phablet-dev-bootstrap emulator $ cd emulator $ source build/envsetup.sh $ lunch aosp_arm-userdebug # or aosp_x86-userdebug for the x86 emulator $ make -j<n>
Note: If you're using Ubuntu Trusty (14.04) as your host, make sure you don't have the package gcc-i686-linux-android installed in your system. This toolchain has a bug that breaks the emulator init system, and you should either use the Android pre-build one (by removing the package), or downloading the latest gcc-i686-linux-android from Ubuntu Utopic (14.10).
To use the system.img that you just created, create an instance with ubuntu-emulator create --use-raw-disk and replace the system.img file available in the generated sdcard.img file (under ~/.local/share/ubuntu-emulator/<my instance>:
$ simg2img out/target/product/generic_x86/system.img out/target/product/generic_x86/system.raw $ sudo mount ~/.local/share/ubuntu-emulator/myinstance/sdcard.img /tmp/mount1 $ sudo mount /tmp/mount1/system.img /tmp/mount2 $ sudo cp out/target/product/generic_x86/system.raw /tmp/mount2/var/lib/lxc/android/system.img $ sudo umount /tmp/mount2 $ sudo umount /tmp/mount1
To build the manager:
sudo apt install golang-go export GOPATH=$HOME/go mkdir $GOPATH export PATH=$PATH:$GOPATH/bin go get launchpad.net/goget-ubuntu-touch/ubuntu-emulator
Username & password are:
phablet phablet
To update your existing working tree to pull in new changes from the server, run repo sync.
For more information about how to use the repo command to manage your android working tree, see this page.
Support Status
Please check Support status to better know what is the current state of the emulator.
Using the emulator
After starting the emulator with the wrapper script, the following should be available:
- Adb
- Emulator will appear in the output of $ adb devices, and will, once fully booted, allow
$ adb shell
access into ubuntu.
- Emulator will appear in the output of $ adb devices, and will, once fully booted, allow
- SSH access
- SSH is enabled by default in the emulator, but you can only access it via localhost (QEMU handles the routes and NAT internally). All you need is to forward the target SSH port to a known port at your host:
$ adb forward tcp:9999 tcp:22 $ ssh phablet@localhost -p 9999
- SSH is enabled by default in the emulator, but you can only access it via localhost (QEMU handles the routes and NAT internally). All you need is to forward the target SSH port to a known port at your host:
- Telnet access
- Once launched, the graphical window title will show a port number, e.g. 5554. Connect to that over telnet to send hardware events to the emulator
$ telnet 127.0.0.1 5554 Trying 127.0.0.1... Connected to 127.0.0.1. Escape character is '^]'. Android Console: type 'help' for a list of commands OK help Android console command help: help|h|? print a list of commands event simulate hardware events geo Geo-location commands gsm GSM related commands cdma CDMA related commands kill kill the emulator instance network manage network settings power power related commands quit|exit quit control session redir manage port redirections sms SMS related commands avd control virtual device execution window manage emulator window qemu QEMU-specific commands sensor manage emulator sensors try 'help <command>' for command-specific help OK
- Once launched, the graphical window title will show a port number, e.g. 5554. Connect to that over telnet to send hardware events to the emulator
- Accessing your host device from the emulator:
You can access your host machine by using the IP 10.0.2.2 from inside the emulator. During development you can either use that to ssh your host, or access any other service running in your host machine, such as a web server.
- Autopilot
Start up emulator with ubuntu-emulator as per above.
- Get emulator serial:
$ adb devices List of devices attached emulator-5554 device emulator-5556 device
Pass -s emulator-XXXX to phablet-config and phablet-test* commands
otherwise use same as described in https://wiki.ubuntu.com/Touch/Testing#Testing_your_Ubuntu_Touch_Code_before_submission, but without "phablet-flash" step for the time being.
Handling disk snapshots
Being able to create a snapshot and roll back to it is very useful for developers. Eg, developers can
- develop features, etc on the image, then package them up, roll back the image and test on a pristine image
- save time on system-image upgrade testing
- do multiple test runs, reverting to the pristine image between runs to cut down on variances
- verify bugs in the image easily
- etc
Instructions
ubuntu-emulator handles disk snapshots:
$ ubuntu-emulator snapshot --help Usage: ubuntu-emulator [OPTIONS] snapshot [snapshot-OPTIONS] Create and revert to snapshots of the emulator instance name 'name' which was previously created Help Options: -h, --help Show this help message Manipulates snapshots for emulator instance named 'name': --revert= Reverts to the selected snapshot --create= Creates the selected snapshot --revert-pristine Reverts to the originally created snapshot Help Options: -h, --help Show this help message
Qcow2 images with snapshots are used by default when creating images with ubuntu-emulator create. The basic workflow is:
$ sudo ubuntu-emulator create trusty $ ubuntu-emulator run trusty <do work> <shutdown or close the emulator with window/ctrl-c> $ ubuntu-emulator snapshot --revert-pristine trusty $ ubuntu-emulator run trusty <perform tests in pristine environment> <shutdown or close the emulator with window/ctrl-c> $ ubuntu-emulator snapshot --revert-pristine trusty
Because a number of things happen on first boot after creating the image (or updating via system-image, which isn't supported yet, but will be), the first boot is very slow. You can workaround this by updating your pristine snapshot after your first boot, like so:
$ sudo ubuntu-emulator create trusty $ ubuntu-emulator run trusty # first boot, be patient and wait until unity8 comes up $ adb shell shutdown -h now # wait until system is halted, then close the emulator with window/ctrl-c $ ubuntu-emulator snapshot --create=pristine trusty
The above boots the emulator, cleanly shuts it down and then updates the pristine snapshot. See ubuntu-emulator snapshot --help for more details.
Keyboard Commands
Emulated Device Key |
Keyboard Key |
Power button |
F7 |
Audio volume up button |
KEYPAD_PLUS, Ctrl-F5 |
Audio volume down button |
KEYPAD_MINUS, Ctrl-F6 |
Switch to previous layout orientation (for example, portrait, landscape) |
KEYPAD_7, Ctrl-F11 |
Switch to next layout orientation (for example, portrait, landscape) |
KEYPAD_9, Ctrl-F12 |
Known Issues
- The first boot might take a few minutes as it generates the ssh key, install the click packages and so on. It shouldn't take too much though, always check with adb if the emulator is still running correctly (e.g. check with top).
- It's quite common for Qemu to hang while booting (like an I/O-type hang), just abort and restart the emulator (still needs proper debugging).
If Unity8 fails to start, make sure your i386 GL driver is properly in place (check for error libGL.so.1: cannot open shared object file: No such file or directory when starting the emulator). If everything goes well, you should see 'qemu.gles=1' in the qemu kernel parameters.
- For running the emulator in a VM guest (e.g. Ubuntu in VMware Player) a VT-d enabled processor is needed and the proper option for supporting nested virtualization must be set in the hypervisor (e.g. in VMware Player the "Virtualize Intel VT-x/EPT or AMD-V/RVI" Option must be set).
Extras
Touch/Emulator (last edited 2016-04-15 03:17:10 by tsimonq2)