===== Building with Docker Containers =====

==== Background ====
In the past we have found it difficult to provide a reliable build environment that could produce the same results as our nightly builds across multiple operating systems.  In the end, we have chosen to use a Docker image to provide an easy to use method to build the Deviation source.  A Docker image is a Linux environment that has been packaged in a way that it can be run from most any PC and will execute precisely the code that we have specified in exactly the same way regardless of what machine you run it on.

==== Requirements ====
If you use a Windows PC, you need:
  * A somewhat recent one which can support Virtualization (this is almost anything made within the last 10 years)
  * Virtualization must be enabled in your BIOS
  * You must be running a 64Bit version of Windows
If you are using a Linux PC, you need:
  * A 64bit variant of Linux
If you are using a Mac, you need:
  * A 2010 or newer Mac with virtualization support.
  * MacOS 10.11 or later.

The [[https://www.docker.com/products/docker-toolbox|Docker Toolbox]] legacy product may work on Windows or Mac that don't meet those requirements.

Next you must install Docker.  Instructions for all operating systems can be found on the Docker site [[https://docs.docker.com/engine/installation/ | here]]

In Windows run the 'Docker Quickstart Terminal' to ensure everything is working properly

NOTE: I have seen some cases on Windows where the installation seems to go okay, but Docker cannot start.  This is an issue with some PCs and VirtualBox (which is installed automatically by Docker).  If you see this error when trying to run Docker 'VERR_INTNET_FLT_IF_NOT_FOUND', then the solution seems to be to uninstall VirtualBox, download the latest version from [[https://www.virtualbox.org/wiki/Downloads | VirtualBox]] and install using 'VirtualBox-5.x.y-zzzzzzz-Win -msiparams NETWORKTYPE=NDIS5'

==== Setting up the Docker Container ====

For Windows users, you should run the 'Docker Quickstart Terminal'.  All of the following commands will be run inside that window.

First, you need to download the Deviation build environment.  From the shell, run:

''docker pull deviationtx/deviation-docker''

This will download the Docker image.  It is a couple hundred Megabytes.

Next you will want to create a directory on your PC where the built firmware can be placed.
''mkdir ~/devo_builds''

Now it is time to create the Docker container.
If you are a user who just wants to build Deviation for your transmitter:

''<nowiki>docker create -it -v ~/devo_builds:/release --name deviation_build deviationtx/deviation-docker</nowiki>''

If you are a developer and have already checked out the Deviation GIT source, you can use:

''<nowiki>docker create -it -v ~/devo_builds:/release -v <path to git>:/git --name deviation_build deviationtx/deviation-docker</nowiki>''

NOTE:  the <path to git> should be the directory above where Deviation is checked out.  E.g. if Deviation is checked out to ~/git/deviation, <path to git> would be '~/git'

==== Building Deviation ====
You can now start the Docker container, and start building Deviation.

To get started run: ''docker start -i deviation_build''

Once you've started the Docker container, it will update to the latest version of the build script, and then will try to checkout deviation if you did not provide a GIT repo.  Next a menu will be shown which allows you to choose what you would like to build.

{{:development:docker_screen.png?600|}}

Initially, 'default' and 'emu_default' are selected.  This will build all zip files that are normally part of a nightly build.

The 'Shell' command will provide an interactive Linux shell inside the image.  This is likely only useful for developers or users familiar with Linux

When you press 'Build' the Deviation images you selected will be built.  If you selected emulator images, some extra libraries will be automatically downloaded and built first.

After the build is complete, the resulting zip files will be placed in ~/devo_builds (on Windows, this will likely be C:\Users\<USER>\devo_builds)

Next time you need to create a new Deviation firmware just follow the instructins in this last section again: [[#Building Deviation]]

==== Developing with Docker ====
The Docker image has been setup with a mechanism to launch a build directly from the native OS.  you must have mounted the git repository as an external volume (see above).  The Deviation repository includes a script called 'dmake' in its root directory.  If you call 'dmake' rather than 'make' it will use a pre-created docker container to run the command specified.

For instance:
''dmake zip_wine_emu_devo12''
will build the Windows Devo12 emulator and create a zip file from it.

Note that unlike using the gui included with the Docker image, the results will not be copied to the /release directory, and instead will remain in the deviation/src dir.  Also, any pre-configuration needs to be done through the docker image gui (for instance if you want to build the windows emulator, you must have built it once through the gui to make sure all required software is installed)

==== Building the Deviation Manual ====
The docker image is also capable of building the deviation manual.
After creating the Docker container, start docker and enter the Shell.
Run: ''%%sudo /root/build.py --manual-prereq%%'' to install the necessary build environment

Next (still from the docker shell), run:
''cd /git; git clone https://github.com/DeviationTX/deviation-manual''

You can now build the manual using make or dmake.

For instance, from within the docker shell run:
''cd deviation-manual; make TARGET=devo10 html pdf''

Or from outside the docker shell (note that this assumes you have added dmake to your PATH):
''cd <path to git repo>/deviation-manual''

''dmake TARGET=devo8 html pdf''