install instructions, discussion of supported OSs

[ghost]

Talking with Neal yesterday at JQI it's clear that not everybody is going to know about how to get ARTIQ up and running with what we've got so far. One improvement is explicit discussion of which OSs are supported. Here's my go. Please add to installing.rst.

Supported OSs

Many laboratory instrument drivers are only available precompiled for Windows. To facilitate use of such hardware devices as ARTIQ supports deployment on 32-bit Windows 7 machines. Presently 64-bit Windows 7, Windows 8 and Windows 10 are not supported.  The most thoroughly tested OSs are Xubuntu 14.04 LTS (64-bit) and ____ (SB fav). NB: Xubuntu is an Ubuntu distribution with the lightweight XFCE user interface. Running ARTIQ on OS X and other versions of Windows is supported using VirtualBox and a Xubuntu.

---

It's also clear not everybody knows how to setup a Virtual Machine. To my view the VM this remains the most straightforward way of getting users up and running ARTIQ. I've edited my VBox instructions for Ion Storage users to make them more generic. I propose including this as an installation subpage.

VirtualBox Setup

Hardware Virtualization

Make sure Virtualization is enabled for your computer

• If Apple machine, it's always on so don't worry
• If Windows machine, make sure hardware virtualization is activated in your BIOS

  Download Xubuntu

• Download Xubuntu 14.04 LTS (64-bit) installation file .iso
• "xubuntu-14.04.x-desktop-amd64.iso" is the file name

  Install Oracle VirtualBox

The operating system (Windows/OSX) that's running the virtualbox is called the Host OS. The virtualized OS (Xubuntu) is called the Guest OS.

• Download VirtualBox and install
• Download and install the VirtualBox Extension Pack
• Run VirtualBox, create a new Virtual Machine
  • New :: Linux , Ubuntu (64-bit)
  • name it xubuntu_artiq
  • Memory size > 1 GB
  • Create dynamically allocated VDI virtual hard disk > 10 GB
  • Settings ::
  • System
    • Allocate at least 2 CPU cores, > 1 GB memory, execution cap 90%
    • Acceleration: enable VT-x/AMD-V and Nested Paging
  • Storage
    • select Controller IDE :: Empty
    • CD/DVD Drive click on disk icon to choose xubuntu installation disk image .iso
  • Shared Folders
    • If you have a favorite native text editor and want to use it instead of Linux tools create a folder that's shared between the Xubuntu virtual machine and your host OS.
    • Create a folder on your host OS (Windows/OSX) that will be used to share files with the guest OS (xubuntu_artiq). On my system this is /Users/myname/virtualMachineShared. Choose this as your Shared Folder for the xubuntu_artiq image. Tick Auto-mount and Make Permanent options.
  • Ports :: USB
    • Enable USB 2.0 controller
    • An explicit step is needed for each USB peripheral connected to your computer to make it available to Xubuntu (e.g. the FPGA board). Plug in your USB devices. They should appear in the list of available USB Device Filters (click green plus sign). Put a tick mark adjacent to the right USB device in the USB Device Filters list. The Pipistrello shows up as "Saanlima Pipistrello LX45 [0700]".
  • Start ::
  • Start the virtual machine. It will boot from the .iso media and begin the Xubuntu installation process.
  • Restart the virtual machine and login.
  • Open a command prompt and proceed with ARTIQ installation

    ARTIQ install

• Precompiled binaries are available to ease installation. The Conda python package manager is used for this deployment and it's included with Anaconda. This includes .bit files for supported FPGAs.
• Follow the instructions for installing using Conda
• Note that Conda installs its own copy of python and python libraries. By default in /home/username/anaconda3/ The implication of this is that you may have two python distributions on your machine: conda's python and the built-in python (as installed via apt-get). ARTIQ uses the conda python and if you want to install additional python packages you should use the conda installer not apt-get. See the Conda FAQ.
• When you install ARTIQ using conda it will place ARTIQ executables in /home/username/anaconda3/bin (e.g. artiq_gui.py)
• Conda does not install the source code for ARTIQ or the example files. Here's how to get them.

  $ mkdir /home/myname/artiq-dev
  $ cd /home/myname/artiq-dev
  $ git pull https://github.com/m-labs/artiq

• If you want to keep up to date with the latest ARTIQ releases use the following

  $ conda install artiq
  $ cd /home/myname/artiq-dev/artiq
  $ git pull

[jordens]

Please clean it up and submit a patch to the manual if you care about this. There is a lot of nonsense and sloppiness in there.

[ghost]

Please be specific about your suggestions. Bare in mind that the developers are not the target audience. I'm not at a machine where I can generate a patch.

On Sat, Jul 4, 2015 at 1:17 PM, Robert Jördens notifications@github.com wrote:

Please clean it up and submit a patch to the manual if you care about this. There is a lot of nonsense and sloppiness in there.

— Reply to this email directly or view it on GitHub https://github.com/m-labs/artiq/issues/64#issuecomment-118535642.

[jordens]

Unless you are willing to get this piece into good shape, write a patch, and keep maintaining/updating it, I suspect it will just hang around here. One reason is that you are the only one making these VMs.

• Most of the sutff is about installing and using virtualbox. Doing a bit of googling and looking at the Ubuntu and Virtualbox documentation shows that there are already tutorials out there. And those are being kept up to date.
• Why 2 CPUs? Why 90% exec cap? Why Xubuntu? Why XFCE? Do those things matter?
• On a 64 bit Intel OS both Python ABI work. 32 bit Python (and ARTIQ) will run fine on 64 bit linux and 64 bit windows.
• A VM for ARTIQ will actually be more work than bare metal. Using a VM here at NIST is subject to the same rules as bare metal. You need to register it with ITAC and have them scan it. And you need to handle their requests. That is also true "just for testing". People need to be aware of that and not pretend VMs are a nice way to get around the work.
• Conda does install the source code.
• On a regular Ubuntu installation you already have several different python trees. Not just one.
• The way to use the anaconda installation is to create an environment and then activate and deactivate it accordingly. See conda/anaconda docs. If you try to manage python packages and run scripts like you describe you will reliably mess up all your python trees: the system's and anaconda.
• Your last two sets of commands will not work. If you want to use the git tree, you need to install/link the git one making sure it takes precedence and probably handle the bitstream compilation (migen, misoc, xilinx). You will also want to uninstall the shipped artiq package.

[ghost]

I agree with Robert that attempting to provide comprehensive and up to date installation instructions for VirtualBox is going to be a lot of work. Work I'm not interested in investing over time. However, I do believe it can be helpful to users if there is a place where we can exchange information on the topic of running ARTIQ on VirtualBox. This thread is a good start.

I propose including a link to this discussion on the ARTIQ installation instructions page. Please flag as area:documentation.

[sbourdeauducq]

How is doing it in Virtualbox different than on a regular PC?

[ghost]

How is doing it in Virtualbox different than on a regular PC?

The stock version of Ubuntu 14.04 includes Gnome and lots of graphics intensive GUI features. VirtualBox is much snappier with XFCE than Gnome. This is why I use Xubuntu 14.04.

When running Linux natively on a PC the hardware Virtualization setting (often in BIOS) ought not to have a performance impact. When running Linux within a VirtualBox environment enabling hardware Virtualization has a large performance improvement.

When running Linux natively on a PC, USB devices are immediately available to Linux. When running Linux within VirtualBox an additional step is needed to make USB devices available to the Guest OS.

The VirtualBox resource configuration recommendations I made suggest that ARTIQ ought to work fine on a resource constrained system. 1 GB memory, 2 cores and 10 GB disk space works for me. Knowing what resource allocation is adequate for ARTIQ is more important on a VirtualBox installation since the Guest OS is sharing resources with the Host OS.