Skip to content

How to run and debug Anki in a Linux virtual machine or in Windows

Jump to bottom Edit New page
Jon Coombs edited this page Aug 22, 2015 · 16 revisions

Technical info on how to run and develop Anki and Anki addons, either on Linux or Windows.

OVERVIEW

Pull the Anki repo from github, and also repos for any add-ons you may be working on. You'll want to run Anki from source in order to be able to debug your add-on code as it runs. A full dev setup will also allow you to build PyQt UI components easily and even tweak Anki's code/UI.

WARNING: Anki does not delete old files when deploying new versions of addons. Avoid renaming files frivolously, especially ones that it will try to automatically load, like flashgr.py (FlashGrid) and syncx.py (FlashGrab).

WARNING: Anki expects addons to be located in %userprofile%/Anki/addons. Those .py files are the ones that will be loaded, and thus the ones you'll see in Eclipse when debugging. If you put the add-on's Git repo somewhere else, be careful to edit the source files rather than the ones the debugger is showing, and then build. Or, you may actually want to set up a backwards 'build' script (BAT file), copying your latest edits from addons over to the repo rather than vice versa.

Most non-UI development is easy enough to set up on Windows (see below), if you don't mind hard-coding a couple of edits to your copy of Anki.

HOW THE LINUX VM CAN BE SET UP

The Linux VM can be used to...

...develop tweaks and addons for Anki. This is why Anki is NOT installed, although several packages it needs are. (See the Anki developer docs if you need to recreate this: ) Rather, you should run Anki directly from source, which means that any tweaks you make will be reflected.

...test those tweaks/addons on Linux. In the case of FlashGrab, it helps to have a LIFT-producing app like FLEx. (Ideally, WeSay too, once a stable version can be pulled from the SIL repos.)

...test Fieldworks on Linux. (SIL repositories are already set up, and a version of FLEx installed.)

For Linux, the simplest option is to use the dev/test VM that I (Jonathan Coombs, SIL) created in 2014.

  • VM: created in Oracle VirtualBox (now using version 4.3.20 r96997

  • Guest OS: Linux Mint 16 Mate 64-bit (basically Ubuntu 13.10)

  • Host OS (shouldn't matter): Win7 Home Premium SP1 64-bit s

  • Host MUST provide a folder mapped as "shared", which will show up in the VM as /media/sf_shared

  • If you have trouble booting the VM, try removing or correcting shared folders pointing to nonexistent targets, or temporarily disabling non-essentials like audio/networking.

    Recommended: keep that "shared" folder right next to the VM's .VDI file on the host machine

    Recommended: keep any source code repositories under "shared", so both OSes can access them. (E.g. you can do all your commit/pull/push actions from SourceTree on the Windows host.)

  • Quick Start for debugging (in Eclipse): put a breakpoint in addons.py under loadAddons() and then launch runanki.py in Debug mode.

    WARNING: On Windows, use a text editor that can understand plain \n newlines as needed.

    WARNING: In the Linux VM, use Eclipse for editing any text files under "shared". Pluma seems to be suffering from a glib bug where Linux text editors that use a temp file (like Pluma) have trouble saving edits properly to Windows SMB shares (although Save As still works): https://bugzilla.gnome.org/show_bug.cgi?id=656225 . Eclipse (under either the host or guest) does not appear to suffer from this bug. (Not sure about nano, emacs, vim, etc.)

RUNNING ANKI ON A DEV MACHINE (I.E. NON-INSTALLED)

To run Anki from source...

  • Windows: run anki.bat

  • Linux: run ./runanki Here's how: adminuser@adminuser-VirtualBox / $ cd media/sf_shared/flashcards/anki/ adminuser@adminuser-VirtualBox /media/sf_shared/flashcards/anki $ ./runanki

  • In Eclipse (either OS), open the runanki file, right-click in it (or set perspective to PyDev and use the Run menu), and choose Run (Ctrl+F11) or Debug (F11).

  • In Eclipse debug mode... You'll want to first set a breakpoint somewhere in the current project. ( E.g. in the main anki project, you might set a breakpoint in aqt/main.py under aqt/setupAddons() or in addons.py under loadAddons(). ) Open runanki and choose Debug from the Run menu. If it can't find the Python interpreter, bump the correct one up (Window, Preferences, Pydev, Interpreters).

Prerequisites: you have to have installed:

  • Python 2 (when installing it on Windows, I'd highly recommend ticking "add to PATH").
  • Java 7 or 8 32-bit (JRE at least)
  • Eclipse 32-bit (I installed the Java EE version of Luna 4.4.1)
  • PyDev
  • mplayer (e.g. install SMPlayer and add ";C:\Program Files (x86)\SMPlayer\mplayer" to PATH and reboot); Anki will run fine without this--until a flashcard tries to play audio.

Do NOT actually install Anki. Rather, run CopyFilesToAddons.bat (or .sh on Linux). Use this to copy changes into the addons folder after any code edit, then restart Anki.

PROJECT INFO

Our projects (besides samples/tests) are:

  • flashgrab (addon)
  • flashgrid (addon)
  • flashfork (addon)

But to actually run/debug those under Anki, we need the anki project too. (Making local edits to this project won't propagate to our users unless the Anki devs accept a pull request from us, but they are very helpful--pretty much necessary on Windows--to do developing/experimenting.)

  • anki (directly runnable; also referenced by our addons);

Eclipse Workspaces ('Solutions') and Projects:

A workspace in Eclipse is much like a solution in Visual Studio. Its info is stored as a hidden .metadata folder, such as:

/media/sf_shared/flashcards/.metadata/

One workspace can contain multiple projects, which you might want to add to one 'working set' for easy global find/replace.

Recommended: as in the current VM, include both addon projects and the anki project (and probably any related sample/test projects) in one "flashcards" workspace.

If you ever have to recreate the workspace, you can delete the .metadata folder and import each project using File, Import, General, Existing...

Similarly, an Eclipse project's info is stored in a hidden .settings folder, but it additionally includes a hidden project file and, for PyDev projects, a hidden pydevproject file.

/media/sf_shared/flashcards/FlashGrab/.settings/

/media/sf_shared/flashcards/FlashGrab/.project

/media/sf_shared/flashcards/FlashGrab/.pydevproject

To recreate a PyDev project, you can delete those and do File, New, Project, PyDev, PyDev. When choosing the Python interpreter, I'd choose "Python 2" as that should pick up the latest 2.x. Remember to recreate any cross-project references.

A COMPLETE DEV/TEST ENVIRONMENT

For more info on how/why the Linux VM was set up, see the anki/README and anki/README.development files, which can also be found here: https://github.com/dae/anki

Basically, it seemed easiest to imitate his Linux dev machine and share that as a VM. However, this helped us learn how to also run from source code (and even build the UI) on the Windows host, so that's great too! For example, to get PyQt4 v4.7+ for Python v2.6+ 32bit (Python's website defaults to 32), I installed PyQt4-4.11.3-gpl-Py2.7-Qt4.8.6-x32.exe from: http://www.riverbankcomputing.com/software/pyqt/download

In Windows, building the UI (e.g. when experimenting with the Anki UI and Qt Designer) is trickier.

  • Individual UI files can be built like this from an ordinary command prompt (creating.py files from Qt's .ui files). C:\Python27\Lib\site-packages\PyQt4\uic\pyuic.py ui_imagedialog.ui > ui_imagedialog.py . For this one-off approach, it's best to append this to your PATH under Control Panel, System, Advance, Environment Variables, System: ;C:\Python27\Lib\site-packages\PyQt4\uic

  • OR, to build the whole Anki app for real, open a Git bash console (e.g. from SourceTree) and do this: cd ../anki tools/build_ui.sh But first you need to change one line in the .sh file to this (or your equivalent):

    C:\\Python27\\python.exe C:\\Python27\\Lib\\site-packages\\PyQt4\\uic\\pyuic.py $i -o $py

    (doing PATH tweaks to avoid changing this one line seems to not be easy)

WARNING: Each time you switch between developing in Eclipse on the Linux guest and on the Windows host, you may need to tell the Eclipse PyDev project which Python interpreter to use. E.g. if I've been developing in Eclipse on Windows and switch to Eclipse on Linux, I'll see C:\Python27\python.exe and /usr/bin/python2 under Windows, Preferences, PyDev, Interpreters and will need to move the second one up.

Add a custom footer
Add a custom sidebar
Clone this wiki locally