Developer Studio uses Docker to provide a Legato toolchain to Windows. Docker is available in a Virtual Machine running in VirtualBox. (Virtual Machine will be called VM in this document)

Prerequisites are:

• Windows 64bits
• Virtualization CPU instructions enabled in BIOS
  • For Intel CPUs, look for VT-x or VT-d
  • For AMD CPUs, look for AMD-V

How to check if my Windows has Virtualization enabled?

Developer Studio Windows installer automatically checks if virtualization option is enabled in the BIOS. If your install is starting, the option is enabled in the BIOS.

Docker Machine setup

Documentation

Docker Machine is a command-line tool used to manage "machines" able to provide a Docker server. Developer Studio is bundling its compatible version of Docker Machine, so there is no need to install it separately.

The only dependency is VirtualBox, which is installed by the Developer Studio Windows installer.

What if VirtualBox is already installed?

If you already have VirtualBox installed, you may not have to re-install it. But please note that Docker Machine 0.6.0 is tested to be stable with a VirtualBox version greater or equals to 5.0.14, so if your VirtualBox is outdated you should update it.

Custom Docker Machine VM

Developer Studio will use its own legato Docker Machine and VM instance to handle Legato application builds.

You can check if the VM is correctly created by starting VirtualBox GUI from the Start menu (on Windows). If you see an instance named legato, the VM has been created.

Note: former versions of Developer Studio were using Boot2Docker, with another VM instance. If you still see a legato-boot2docker-vm VM in VirtualBox, you can safely remove it.

How-to access your Docker machine

To get a shell inside the VM, you have two ways.

The easy way is to start the VM directly using VirtualBox GUI

• Open VirtualBox GUI (from the start menu on Windows)
• Find the VM named legato
• If it is already started, stop it with the righ click menu
• Start it from the right click menu or double click on it
• A window pops up and after the boot sequences, you have a shell prompt to run commands like docker images

The complex way uses Docker Machine CLI to directly login via SSH an already running VM

• Open cmd.exe
• Use cd commands to navigate to your Developer Studio installation folder
• Type cd plugins then type dir, you should see a com.swi.spm.legato.docker.machine.win32.x86_64_X.X.X folder. Go in this folder with the cd command, then type cd os\win32
• You can get the machines list and status with command docker-machine ls
• You can start/restart the VM with command docker-machine start legato or docker-machine restart legato
• You can run remote commands like docker-machine ssh legato docker images
• To login into the VM using SSH type docker-machine ssh legato

What if your Docker machine doesn't start?

You have several options to try when your Docker Machine VM doesn't start (either from Developer Studio or from the command line):

• Check the virtualization option is enabled in the BIOS (see above)
• Restart your Windows computer (VirtualBox installs network interfaces, and on some systems a reboot is necessary to have these interfaces working correctly)
• Sometimes Docker machine creation does not success, and the resulting machine is not usable. To diagnose this state, you can try the following command sequence (cf. above to know where to execute the docker-machine utility):
  • docker-machine env legato --cmd shell; if the command complains that certificates are missing, it is necessary to regenerate them, with the following commands
  • docker-machine restart legato to restart the VM
  • docker-machine regenerate-certs legato to regenerate the certificates
  • Then verify that docker-machine env legato --cmd shell is running without errors
• Try to delete and recreate the VM:
  • docker-machine rm legato
  • if docker-machine ls still complains about files that can't be read for legato VM, delete your %USERPROFILE%\.docker folder (usually C:\Users\%USERNAME%\.docker)
  • Then trigger a Legato application build in Developer Studio interface
• Check your VirtualBox version, especially if you installed it some time ago
• Check the network configuration of the VM in your VirtualBox GUI
• Try to remove all the machines, check the VMs are also removed in VBox interface, and use VBox preferences menu to uninstall all the unused virtual network cards from your system
• Refer to the error reported by VirtualBox (in the GUI, or when using docker-machine -D start legato (verbose mode)) to try understanding the issue

Do I have to keep the Legato VM in VirtualBox?

Nothing important is stored in this VM, you can delete it whenever you want. Developer Studio will re-create it, start it and download all the Docker images it needs automatically.

Your Developer Studio workspace is shared with the VM. So you build your projects with Docker directly in your workspace on Windows.

You may want to run some commands from the VM for troubleshooting.

Docker provisioning

Developer Studio needs 3 images to build your Legato projects

1. legato/framework contains the framework which has been built for your device.
2. legato/toolchain contains the toolchain.
3. legato/ds-runtime which is a customized Ubuntu with all dependencies to compile Legato projects.

Check what are fetched images and running containers in the Docker machine

Developer Studio integrates tooling from the Eclipse community to have a look into the Docker machine.

Just open the Docker Images and Docker Containers view in Developer Studio.

How-to manually use docker images

You need to login the VM, see how-to in the previous section.

When you have a prompt inside the VM, use the command docker images to list all images that have already been downloaded.

docker@boot2docker:~$ docker images
REPOSITORY          TAG                                                  IMAGE ID            CREATED             VIRTUAL SIZE
legato/ds-runtime   a                                                    cd6118b47bcf        5 weeks ago         395.7 MB
legato/framework    15.05.0.Beta                                         e42fdbe991dd        5 weeks ago         91.36 MB
legato/toolchain    1.6.2.fw_SWI9X15A_06035400-wp7-x86_64-201506091530   40e185980c6e        5 weeks ago         548.3 MB

To download manually an image

docker@boot2docker:~$ docker pull legato/framework:15.05.0.Beta
Pulling repository legato/framework
e42fdbe991dd: Download complete
cf2616975b4a: Download complete
6ce2e90b0bc7: Download complete
8c2e06607696: Download complete
ed18f45c78ce: Download complete
Status: Image is up to date for legato/framework:15.05.0.Beta

To clean your VM you could delete all containers (keep in mind that Nothing important is stored in this VM, you won't loose any important data).

docker@boot2docker:~$ docker ps -aq | xargs docker rm -vf
c413f0a348ec
2b90d7aca064

Workspace sharing

The workspace folder is shared with the VM via VirtualBox sharing system. As a result, only projects located inside your workspace will be visible in the runtime container.

Linked projects

Developer Studio can import or create projects that are located in another folder than the workspace, like a link. You can use Developer Studio preferences to bind any folder out of the workspace to a location inside the Docker runtime container.