A quickstart guide to the Ubuntu emulator

Ubuntu emulator guide

Following the initial announcement, the Ubuntu emulator is going to become a primary Engineering platform for development. Quoting Alexander Sack, when ready, the goal is to

[…] start using the emulator for everything you usually would do on the phone. We really want to make the emulator a class A engineering platform for everyone

While the final emulator is still work in progress, we’re continually seeing the improvements in finishing all the pieces to make it a first-class citizen for development, both for the platform itself and for app developers. However, as it stands today, the emulator is already functional, so I’ve decided to prepare a quickstart guide to highlight the great work the Foundations and Phonedations teams (along with many other contributors) are producing to make it possible.

While you should consider this as guide as a preview, you can already use it to start getting familiar with the emulator for testing, platform development and writing apps.

Requirements

To install and run the Ubuntu emulator, you will need:

  • Ubuntu 14.04 or later (see installation notes for older versions)
  • 512MB of RAM dedicated to the emulator
  • 4GB of disk space
  • OpenGL-capable desktop drivers (most graphics drivers/cards are)

Installing the emulator

If you are using Ubuntu 14.04, installation is as easy as opening a terminal, pressing Ctrl+Alt+T and running these commands, followed by Enter:

sudo add-apt-repository ppa:ubuntu-sdk-team/ppa && sudo apt-get update
sudo apt-get install ubuntu-emulator

Alternatively, if you are running an older stable release such as Ubuntu 12.04, you can install the emulator by manually downloading its packages first:

Show me how

  1. Create a folder named MARKDOWN_HASHb3eeabb8ee11c2be770b684d95219ecbMARKDOWN_HASH in your home directory
  2. Go to the goget-ubuntu-touch packages page in Launchpad
  3. Scroll down to Trusty Tahr and click on the arrow to the left to expand it
  4. Scroll further to the bottom of the page and click on the MARKDOWN_HASH05556613978ce6821766bb234e2ff0f2MARKDOWN_HASH package corresponding to your architecture (i386 or amd64) to download in the MARKDOWN_HASH1e681dc9c2bfe6538971553668079349MARKDOWN_HASH folder you created
  5. Now go to the Android packages page in Launchpad
  6. Scroll down to Trusty Tahr and click on the arrow to the left to expand it
  7. Scroll further to the bottom of the page and click on the MARKDOWN_HASH1843750ed619186a2ce7bdabba6f8062MARKDOWN_HASH package corresponding to download it at the same MARKDOWN_HASH1e681dc9c2bfe6538971553668079349MARKDOWN_HASH folder
  8. Open a terminal with Ctrl+Alt+T
  9. Change the directory to the location where you downloaded the package writing the following command in the terminal: MARKDOWN_HASH8844018ed0ccc8c506d6aff82c62c46fMARKDOWN_HASH
  10. Then run this command to install the packages: MARKDOWN_HASH0452d2d16235c62b87fd735e6496c661MARKDOWN_HASH
  11. Once the installation is successful you can close the terminal and remove the MARKDOWN_HASH1e681dc9c2bfe6538971553668079349MARKDOWN_HASH folder and its contents

Installation notes

  • Downloaded images are cached at ~/.cache/ubuntuimage –using the standard XDG_CACHE_DIR location.
  • Instances are stored at ~/.local/share/ubuntu-emulator –using the standard XDG_DATA_DIR location.
  • While an image upgrade feature is in the works, for now you can simply create an instance of a newer image over the previous one.

Running the emulator

Ubuntu emulator guide

The ubuntu-emulator tool makes it again really easy to manage instances and run the emulator. Typically, you’ll be opening a terminal and running these commands the first time you create an instance (where myinstance is the name you’ve chosen for it):

sudo ubuntu-emulator create myinstance --arch=i386
ubuntu-emulator run myinstance

You can create any instances you need for different purposes. And once the instance has been created, you’ll be generally using the ubuntu-emulator run myinstance command to start an emulator session based on that instance.

Notice how in the command above the --arch parameter was specified to override the default architecture (armhf). Using the i386 arch will make the emulator run at a (much faster) native speed.

Other parameters you might want to experiment with are also: --scale=0.7 and --memory=720. In these examples, we’re scaling down the UI to be 70% of the original size (useful for smaller screens) and specifying a maximum of 720MB for the emulator to use (on systems with memory to spare).

There are 3 main elements you’ll be interacting with when running the emulator:

  • The phone UI – this is the visual part of the emulator, where you can interact with the UI in the same way you’d do it with a phone. You can use your mouse to simulate taps and slides. Bonus points if you can recognize the phone model where the UI is in ;)
  • The remote session on the terminal – upon starting the emulator, a terminal will also be launched alongside. Use the phablet username and the same password to log in to an interactive ADB session on the emulator. You can also launch other terminal sessions using other communication protocols –see the link at the end of this guide for more details.
  • The ubuntu-emulator tool – with this CLI tool, you can manage the lifetime and runtime of Ubuntu images. Common subcommands of ubuntu-emulator include create (to create new instances), destroy (to destroy existing instances), run (as we’ve already seen, to run instances), snapshot (to create and restore snapshots of a given point in time) and more. Use ubuntu-emulator --help to learn about these commands and ubuntu-emulator command --help to learn more about a particular command and its options.

Runtime notes

  • Make sure you’ve got enough space to install the emulator and create new instances, otherwise the operation will fail (or take a long time) without warning.
  • At this time, the emulator takes a while to load for the first time. During that time, you’ll see a black screen inside the phone skin. Just wait a bit until it’s finished loading and the welcome screen appears.
  • By default the latest built image from the devel-proposed channel is used. This can be changed during creation with the --channel and --revision options.
  • If your host has a network connection, the emulator will use that transparently, even though the network indicator might show otherwise.
  • To talk to the emulator, you can use standard adb. The emulator should appear under the list of the adb devices command.

Learn more and contribute

I hope this guide has whetted your appetite to start testing the emulator! You can also contribute making the emulator a first-class target for Ubuntu development. The easiest way is to install it and give it ago. If something is not working you can then file a bug.

If you want to fix a bug yourself or contribute to code, the best thing is to ask the developers about how to get started by subscribing to the Ubuntu phone mailing list.

If you want to learn more about the emulator, including how to create instance snapshots and other cool features, head out to the Ubuntu Emulator wiki page.

And next… support for the tablet form factor and SDK integration. Can’t wait for those features to land!

, , ,

  • Suresh Naik

    I was unable to install the emulator from sudo apt-get install

    and from the manual process also

    • http://lucas.gd/ Lucas

      Which version of Ubuntu do you use? 12.xx, 13.04 or 12.10? :)

      • Suresh Naik

        It’s ubuntu 13.10

        • akas

          I had the same issue. Try
          1. sudo apt-get install -f
          2. sudo dpkg -i *.deb
          It should install without any errors!

          • Suresh Naik

            I did these
            I had the same issue. Try
            1. sudo apt-get install -f
            2. sudo dpkg -i *.deb

            after posting my first comment and it had installed properly.
            Problem is while running the emulator it’s opening the black screen but showing anything after that It is just sopping there

          • akas

            It will ask for username and password in the terminal. Enter “phablet” for both. The emulator will take a lot of time to startup. Have patience! :)

          • Suresh Naik

            I entered the right username and password but that time because of some reasons that software colsed unexpectedly. But now its working fine :)

          • http://davidplanella.org/ David Planella

            Excellent, glad to hear it worked for you in the end!

          • Hongkun Li

            I got the same problem.. But the emulator just leaves me a black screen.I really don’t know how to handle this…
            Could U help me?

    • Brian Perry

      Me too. I got errors when I used the command.

    • http://davidplanella.org/ David Planella

      Could you give some more information on what exactly did not work? And what version of Ubuntu you are running?

  • Guest

    When I give sudo ubuntu-emulator create myinstance the terminal downloads a file of around 285mb. Is that supposed to happen?

    • http://davidplanella.org/ David Planella

      That’s to be expected, yes. Also make sure that you’ve got 4 Gb of free space as mentioned in the requirements.

  • Anonymous 2358

    There’s an ubuntu-emulator package for amd64, but ubuntu-emulator-runtime is only available for i386. What’s the deal?

    • Anonymous 2358

      Your howto for users on 13.10 is wrong. ubuntu-emulator-runtime doesn’t exist for amd64.

  • rschroll

    On 12.04, the create process ends with the error:

    Error while converting /home/rschroll/.local/share/ubuntu-emulator/testinstance/system.img: Unknown option ‘compat’
    qemu-img: Invalid options for file format ‘qcow2′.

    This doesn’t seem to actually be a problem; I can run the emulator after this. Just thought you might want to know.

    • http://davidplanella.org/ David Planella

      Thanks for the heads up, I’ll pass on the feedback to the developers. And thanks for confirming it works on 12.04!

    • lathrisk

      I had this problem and an identical output on 12.04 but following this I get:
      “Search configured emulator instances.
      Detecting device..
      * there is no device connected.”

      And the process appears to end.

  • Alex Thierry

    When you write it takes a while to load, I could not imagine how long it could be…How can I check if it’s loading or if it’s bugging?

    • http://davidplanella.org/ David Planella

      It does take a while, yes, and it can be in the order of minutes. However, if you’ve gone for a tea and when you’re back it’s still not loaded, it might be worth restarting it and checking that you don’t have any other running apps using a lot of memory or CPU, as the emulator tends to be out or memory or take a longer time to load, then.

  • http://leolik.blogspot.com/ Leolik

    UI is very slow. It’s ok?

  • gtriderxc

    ubuntu-emulator doesn’t exist in my software sources on a fully updated 12.04

    • akas

      I think you are trying to install Ubuntu Emulator using “sudo apt-get install ubuntu-emulator” That only works if your are using 14.04. Scroll above and under the topic “Installing the Emulator” click on the link that says “Show Me How ” and follow the instructions for 12.04.

  • peterdroid

    Thanks for the links to ubuntu emulator and emulator runtime.. the official docs somehow thought that everyone has the Trusty ubuntu

  • PrasannaKumar Muralidharan

    Errors while running “sudo ubuntu-emulator create UbuntuTouch”:
    Creating “UbuntuTouch” from devel-proposed revision 154
    Downloading…
    Cannot download {87304baf144272bab99db0f054c32a62d24c455392b150469222f5aeea38e69b /pool/ubuntu-8d9260d5f7309451f46761b580ea853e0fbe99fe1d4dc6aecd1e6f26afa4e0f9.tar.xz /pool/ubuntu-8d9260d5f7309451f46761b580ea853e0fbe99fe1d4dc6aecd1e6f26afa4e0f9.tar.xz.asc %!s(int=329023340) %!s(int=0)}

    Any help in solving this will be great.

    • PrasannaKumar Muralidharan

      Any clue on this? I am running Ubuntu 13.10 amd64 desktop edition.

      • Sven Bendel

        Got exactly the same problem with exactly the same configuration. When creating the emulator from the IDE the image is downloaded correctly. However it doesn’t boot up completely – the emulator screen will remain blank forever. However I can login to the remote session.

        • PrasannaKumar Muralidharan

          I am not able to find an option to create an emulator in IDE. How to do that?

          • Sven Bendel

            Click on devices on the left pane in the IDE. Then open the emulators tab and type in a name on the left side of the screen. Clicking “Create” (or something similar, don’t have my laptop at hand right now) will create a new emulator instance for you. After this is done you can start the new instance on the right side of this tab. This is where things got tricky in my case as the emulator just stopped booting in the middle of the process leaving me with a blank emulator screen.

          • PrasannaKumar Muralidharan

            There is no emulator tab in the IDE unfortunately. What should I do? I am running Qt creator 2.7.1.

          • Sven Bendel

            Well, I’m on Qt creator 2.8.1. Maybe you should consider upgrading?

          • PrasannaKumar Muralidharan

            I don’t see any updates to Qt creator in synaptic. 2.7.1 is the latest version according to it. Any problem in my system configuration?

          • Sven Bendel

            As recommended here

            http://developer.ubuntu.com/apps/sdk/tutorials/installing-the-sdk/

            you should use this PPA to get the current Qt Creator builds:

            ppa:ubuntu-sdk-team/ppa

          • PrasannaKumar Muralidharan

            After adding the PPA there was an update for qtcreator and ubuntu plugin. Installed it, now qtcreator seg faults upon launching :(.

            Anyway thanks for taking your time.

          • Sven Bendel

            I’m sorry, but that’s just what I did. However, as I already mentioned, I just can create a new emulator, but never got it to work properly. So maybe we just have to wait until the emulator is a little bit more mature and in the meantime use qmlscene for testing our code. I agree, that this is somewhat disappointing.

  • nocomp

    pls replace ubuntu-emulator run myinstance by sudo ubuntu-emulator run myinstance and then it will work ;)

  • Pingback: Ubuntu Touch Emulator: Installation And Usage In Ubuntu 14.04, 13.10 And 12.04 | Misiongeek()

  • Pingback: Ya está disponible el emulador de Ubuntu Touch()

  • http://daniel-beck.org Daniel Beck

    This quickstarts explains how to install the arm emulator. However, the following link states that the x86 emulator is much faster an should be installed instead: http://www.bestubuntu.com/ubuntu-touch-x86-emulator-better-emulator-performance-faster-startup-ubuntu-installation-instructions.html

    What emulator should we install?

    • http://davidplanella.org/ David Planella

      Hi Daniel, for some reason I had missed your comment, sorry. In any case, I updated the guide a while ago to explain how to create i386 instances, which are what I’d recommend now, as they run at native speeds.

  • Jef Spaleta

    any plans to make the emulator a compilable from source project? So I can getting running outside of Ubuntu?

    • http://davidplanella.org/ David Planella

      Hi Jef, sorry for the late reply. You’ll find the sources for the emulator here: https://launchpad.net/goget-ubuntu-touch/trunk – I’m not sure what you mean by “compilable from source”. Any Ubuntu package is compilable from source, so you should be able to compile it on Fedora too. That said, it might require some dependencies only available on Ubuntu or Debian, so I guess it’s a matter of trying and seeing if it just works or if any packages need to be ported/updated in Fedora (or any other distro)

      • Jef Spaleta

        pardon… but does that launchpad project also include the source for ubuntu-emulator-runtime package?

        Because I’m looking through the debian control file and the ubuntu-emulator package derived from the sources you just pointed me in all the branches I’ve looked at depends on ubuntu-emulator-runtime… which as far as I can tell is a built from entirely different sources which seems really odd to me.

        what the hell man…. the “runtime” isn’t part of the “sources”… are you kidding me?!? Really?!? Wow. That feels a bit like your patronizing me a bit and just wasting my time. But I’ll let it slide.

        In fact the ubuntu package search webservice tells me ubuntu-emulator-runtime is only available in trusty…in the “android” package… are you kidding me?!? No Utopic package … provide this dep? So I can’t build this against utopic? wtf….just trusty….bleech.

        Looking at the android launchpad project page…and finding the branch for the code marked for Utopic development…the package no longer provides the dependence..The branch described as being for Utopic development doesn’t actually
        have the depdency… WTF man!?! Where is the coherent development tip of this piece of software?

        And there are no useful instructions right now which tell me which fracking branches are the … canonical… branches to use to make a coherent lump of functionality work as expected for all the non-versioned moving pieces in launchpad. You think your are being helpful with the pointer to the launchpad page.. but you are not. This sort of response is just frustrating because the development model Canonical uses for inhouse projects is so myopically focused on the Rube Goldberg machine that is launchpad buildsystem workflow. Just pointing to a launchpad page for any lump of code is absolutely useless because inevitably that code depends on a specific branch of dependent code in another launchpad project and none of it is coherently documented in the public facing project instructions.. the relationship as to which branches work together to form the development tip is buried somewhere else. And there’s no jhbuild-like script to automate that relationship for anyone walking into the development.

        Meh.. this is the same sort of thing..I went through with Mir tryiing to find all the relevant sources to get Mir to build from source cleanly. Bah….

        Too bad there aren’t clean and accurate build from source instructions. But i’ve pretty much given up expecting coherent build from source instructions for Canonical in-house projects. Its just code over the wall…always just code over the wall.

        If the emulator can only be effectively spun up on Ubuntu.. its pretty much DOA as far as a useful emulator goes. You have to get this spun up on MS and OSX devel boxes so existing app developers can taste the rainbow of the Uphone and port to it without going 100% Uwork environment. Yeesh.

        And without coherent and accurate build from source instructions that do not depend explicitly on Ubuntu specific packaging.. how in the hell do you expect anyone outside the corporate fenceline help you make sure the emulator is available cross-platform? Or maybe you don’t expect anyone to help… maybe you expect Canonical to have the manpower to spin up emulator as a cross-platform tool… don’t hold your breath.

        But thanks for the launchpad project pointer….for whatever that’s worth.

        • http://davidplanella.org/ David Planella

          Wow, Jef, I was genuinely just trying to be helpful… I wasn’t really expecting that kind of reply.

          In any case, I will try to find out more, but developing the emulator itself is not my area of expertise.

          • Jef Spaleta

            the wiki instructions implicitly assume you are on an Ubuntu release (don’t even work for Debian)… so not as helpful as one would think by just reading the section heading. Or to be snarky about it. Those instructions are about as “from scratch” as my imfamous “from scratch” chocolate chip cookies that I bake using a recipe that calls for store bought philsbury cookie dough.

            That phablet bootstrapping stuff only works on Ubuntu…because phablet-tools is only packaged for Ubuntu. And there are no instructions outside of the debain control file in the phablet-tools codebase which make any effort at all to codify why phablet-tools needs to build. And even those are a bit silly, encoding all sorts of debian packaging specific things just to appease the Ubuntu build system. The wiki’s aptget instructions don’t work on Debian as phablet-tools is an Ubuntu only package… and on and on and on as many of the things that package depends on are ubuntu only. It’s a deep dark rabbit hole of pain. Do I really need to install the click software to get phablet-tools compiled and installed and running? Debian control says its a runtime depend..but is it really a hard depend? Or is it just an Ubuntu integration dependency? No idea… nobody has documented phablet-tools deps well enough to make a determination as to what is a hard and what is a soft dep or entirely optional functionality.

            Once again… the build from scratch instructions aren’t really…build from scratch. Same exact situation I had with Mir’s original build from source instructions until I got mad and said something about how terrible they were if you actually want to build from source.

            So looking at those not-so-from-scratch instructions and the packages being pulled in….basically the emulator needs pretty much everything being spun up inside the bounds of the phablet-team. Fantastic…. too bad none of that stuff has documented well enough to make a good stab at rebuild cleanly on Debian…let alone any target where dpkg isn’t going to be available without also building it from source.

            I understand you are trying to be helpful. It’s not your fault that the source build instructions are never appropriately crafted for Canonical projects that have cropped up in the last 4 years or so. Canoncial engineering management just doesn’t make documenting compile from source important enough for anyone to spend time doing so its not done. The goal is clearly to do the minimum required to get the debian control file working with the Ubuntu build system and call it a day. There’s no separation between upstream project best practises and distribution packager policy in how these projects are managed. It is what it is, and makes working with Canonical built project code, a pain the ass, more times than not.

            Not your fault, and believe me when I say I’m only showing you about 0.01% of the heat level I actual feel when reading over the source and the terrible build from scratch instructions. honestly, I don’t even know why I still bother, I would have hoped after Mir this would get better…but clearly not.

            I’ll try to remember to watch the wiki for updated “from scratch” instructions that actually work “from scratch” and don’t depend on Ubuntu only packages. But I’m not holding my breath. Hopefully other people come along from outside the Ubuntu userbase with the time and energy to beat on this particular brickwall of getting the emulator spun up on targets outside of Ubuntu.

            Canonical really does need to get this emulator working on other vendor targets to increase reach into the app developer community. It has to compete with the reach of Android’s SDK and the emulator that comes with it. Now if Ubuntu’s virtual images used in the emulator were strictly compatible with android’s existing emulator framework… problem solved. But I’m getting the sense looking at all the code here that this is yet another embrace and extend situation..that Canonical has engaged in. Where they’ve taken android’s existing open source emulator framework has been tweaked a bit to be born anew as the ubuntu-emulator…but without a plan to make ubuntu-emulator available cross-platform. I had some hope for the emulator. I have less hope now.

            -jef

          • Jef Spaleta

            to put a finer point on what I’m trying to say. Please read the instructions for what Google provides for build from source instructions for the android emulator. Especially the Mac OSX specific instructions…

            Everything they reference as a build requirement on Ubuntu are externally produced project that is also available prepackaged on Debian (and well every other distro i’ve looked at really). Those instructions actually work on Debian (well and Fedora as it turns out) without having to hunt around for Google specific codebases or worse specific repository branches. Absolutely no in-house Google project code is specified as a binary dependency to build the Android SDK+emulator. It’s just pretty standard general purpose build stuff. Well the multiarch stuff is a little Debian ecosystem specific but its not a huge difference nor is it a problem.

            And in fact the android build from source does exactly what I would expect… it provides a tool.. the repo tool.. which pulls _all_ the Google code down from multiple project repositories to build the emulator self-consistently. Its very much like GNOME’s jhbuild automation in fact. Well done Google.

            Ironically, the Ubuntu emulator development relies heavily on the engineering Google put into the repo tool…since the U emulator uses that repo tool to basically build the android emulator as a prereq to extend. But Canonical didn’t pay the benefit inherent in the repo tool forward for anyone interested in building Uemulator from source. They didn’t just extend that very nice source level tool Google has provided so that it pulls all the Canonical bits that the U emulator needs like phablet-tools and click package sources and all that crap. No U emulator development just relies strictly on all the moving pieces that Canonical is working on, being pre-packaged and pre-seeded binaries. Not good. Definitely not good. Canonical is making it so much harder for themselves to get the emulator in from of Mac OSX devs than it should be by relying so heavily on the Ubuntu specific build system and packaging policy for pieces of the code.

            If Google engineered their development workflow the same way Canonical has choosen, it would be freakin impossible for them to offer build from source instructions that work coherently on Mac OSX. As it will be for Canonical.

            Canonical is sinking their own boat by not making sure the emulator development workflow treats Mac OSX as a first tier target along side Ubuntu desktop. Canonical has to get the U emulator on Mac OSX systems, that’s where the huge pool of app developers live, right now. App developers with Mac OSX development machines need to be able to grab the Uemulator master sources and build it as easily as they build Android emulator so they can participate in Uphone using the environment that are right now most familiar with. Forcing them to jump into a Udesktop to work on Uphone apps is a pretty steep hill to climb for such little return on investment.

            -jef

        • http://davidplanella.org/ David Planella

          Ok, so it seems that the wiki page pointed out in the post contains the build instructions: https://wiki.ubuntu.com/Touch/Emulator#Building_from_scratch – for any questions or issues with the build, I’d recommend asking on the #ubuntu-touch IRC channel on Freenode or on the ubuntu-phone@lists.launchpad.net mailing list, as there the experts can answer in more detail.

  • Someone2

    Wow! You got more then 720GB of memory?

  • Thibaut B.

    The i386 emulator works, but the Dash is empty and there seems to be no installed apps beside of the apps in the launcher (browser, settings…).

    The other question is how to update the used emulator image? Is it possible to update the OS inside the emulator or do I have to run ‘ubuntu-touch create’ every time?

    And I get a lot of these errors:
    * Setting up X socket directories… [ OK ]
    sdk/emulator/opengl/host/libs/Translator/GLES_V2/GLESv2Imp.cpp:glReadPixels:1610 error 0x500