====== Building the Digilent Agent From Source ======
This page describes the process of building the Digilent Agent from source.  

**//Note: This process is recommended for advanced users only and most users should install one of the existing builds [[software:digilent-agent:start| available here]]. //**

===== Windows =====
----
  * Install [[https://www.qt.io/download/ | QT Creator 5.7]] or newer.
  * Install [[http://download.qt.io/official_releases/qt-installer-framework/ | QT Installer Framework 2.03]] or newer.
  * Ensure the QT and QT installer framework binaries are on the system path:
    * <code>C:\Qt\5.11.1\mingw53_32\bin</code>
    * <code>C:\Qt\QtIFW-3.0.4\bin</code>
  * Clone the [[https://github.com/Digilent/digilent-agent | Digilent Agent]] repository.
  * Initialize and update git submodules
    * <code>git submodule init</code>
    * <code>git submodule update</code>
  * Launch the QT project 'digilent-agent.pro'.
  * Press **Ctrl+R** to build or **F5** to build in debug mode.

=== Installer ===
  * Hard link the debug and release build outputs into the project **root directory**. Ex:
      * <code>New-Item -ItemType Junction -Name debug -Value ..\build-digilent-agent-Desktop_Qt_5_11_1_MinGW_32bit-Debug\debug\</code>
      * <code>New-Item -ItemType Junction -Name release -Value ..\build-digilent-agent-Desktop_Qt_5_11_1_MinGW_32bit-Release\release\</code>
  * Set the version number in **agent.cpp**.
  * Use QT to build a release build in the **release** folder at the project root.
  * Set the version number in **installer/config/winConfig.xml**.
  * TODO - REMOVE - Set the version number in **installer/packages/com.digilent.agent/meta/winConfig.xml**.
  * Use CygWin to enter the **installer** directory at the project root.
  * Run the build script with the following command
  * <code bash>./build.sh win <VERSION_NUMBER> <RELEASE_TYPE></code> \\ ex. <code>./build win 1.0.0 release</code>
  * The installer will be created in the **installer** directory at the project root.

===== Linux =====
----
  * (Optional - provides GUI IDE and debugging) Install [[https://www.qt.io/download/ | QT Creator 5.7]] or newer.
  * Update the package feeds. <code>sudo apt-get update</code> \\ 
  * Install QT5 <code>sudo apt-get install qt5-default</code> \\ 
  * Install QT5 serial port support<code>sudo apt-get install libqt5serialport5-dev</code> \\ 
  * Clone the Digilent Agent repository <code>git clone https://github.com/Digilent/digilent-agent.git</code> \\ 
  * Enter the repo directory <code>cd digilent-agent</code> \\ 
  * Initialize and update the submodules (Digilent qtSerial and pgm) <code>
git submodule init
git submodule update
</code> \\ 
  * Run qmake <code>qmake</code> \\ 
  * Build the Digilent Agent <code>make</code> \\ 
  * Run the Digilent Agent (Read/Write permission for UART devices is required) <code>./digilent-agent</code> \\

===.deb ===
  * Build release using qmake and make as described above.
    * This step is to confirm everything is setup correctly and can technically be omitted as the deb build script will rebuild everything form source.
  * Open a terminal in the **installer** directory at the project root.
  * Run the build script with the following command
  * <code bash>./build deb <VERSION_NUMBER></code> \\ ex. <code>./build deb 1.0.0</code>
  * Follow the instructions in the terminal.
  * The .deb will be created in the **installer** directory at the project root.

===== Mac =====
Install [[https://www.qt.io/download/ | QT Creator 5.7]] or newer.
  * Clone the [[https://github.com/Digilent/digilent-agent | Digilent Agent]] repository.
  * Initialize and update git submodules
  * <code>git submodule init</code>
  * <code>git submodule update</code>
  * Build from command line
    * Run: <code>qmake</code>
    * <code>make</code>
  * **Or** build from QT Creator:
    * Press **Ctrl+R** to build or **F5** to build in debug mode.
  * Build Signed .dgm
    * Enter the  **installer** sub directory. <code>cd installer</code>
    * Run the build script to package dependencies, sign the .app and build the .dmg <code>./build.sh osx <VERSION> release</code>
      * Where <VERSION> is the release version (ex. 1.0.1).

**Or**

Generate an Xcode Project:

<code>qmake -spec macx-xcode digilent-agent.pro</code>
  * Add images/icon.iconset to digilent-agent/Resources in Xcode
//Note: If the **digilent-agent.entitlements** is red in Xcode you may have to delete the file and use Xcode to manually create an **Poperty List** file named digilent-agent.entitlements in the project root. // 




=== Build a new .dmg ===
  * Build a release version of the Digilent Agent using QT.
  * Use [[http://doc.qt.io/qt-5/osx-deployment.html | macdeployqt]] to build a distributable .app. \\ <code>macdeployqt Digilent\ Agent.app/ -codesign=<ID> -always-overwrite</code>
  * Use **Disk Utility** to create a new disk image.
    * Name the image digilent-agent-<VERSION>.dmg where <VERSION> is of the form #.#.# (ex. 1.0.3)
    * Set the image size to be just large enough to hold the Agent and WaveForms Live offline support (~20 MB).  The size cannot be changed later.
    * Set the Image Format to read/write disk image.
  * Mount and open the disk image.
  * Click **View>>as Icons** to ensure the disk image contents is viewed as icons.
  * Copy and paste the **.app** file from the QT release build folder into the mounted disk image.
  * Create a shortcut to the **Apps** directory in the mounted disk image.
  * Copy and paste the **WaveForms-Live** offline support into the mounted disk image.
  * Create a shortcut to the **share** directory in the mounted disk image.
  * (Optional) add a background image.
    * Copy and paste an image file into the mounted disk image.
    * With the mounted disk image active select **View>>Show View Options**.
    * Under the **Background:** section click **Picture**
    * Drag the image from the mounted disk image to the picture box.
    * Use the terminal to hide the image file (change the name to start with a '.'). \\ <code>cd /Volumes/<DISK_IMAGE_NAME></code><code>mv <FILENAME> .<FILENAME></code>
  * Unmount the disk image.
  * Use Disk Utility to convert the disk image into a read-only copy.
    * **Images>>Convert**
    * Select the disk image and click **Open**.
    * Set the **Image Format** to **read-only**.
    * Click **Save**.
  * Distribute the read-only copy of the disk image.
  * Keep the read-write copy of the disk image to simplify future updates.

{{tag>digilent-agent tutorial build}}