# CENOS Backend - Build Instructions

## Building on Windows

### Machine
-  Windows 10 64-bit

### Programs

Git
- [git](https://git-scm.com/download/win)
- [Git Extensions](http://gitextensions.github.io/) or other git GUI (skip if you are git CLI guru)
- [Git LFS (Large File Storage)](https://git-lfs.github.com/)  
  It might be installed with GitExtensions. Check with
  ```
    $ git lfs install
    > Git LFS initialized.
  ```

Install the following (tested versions are mentioned in brackets):
- Visual Studio 2019 Community (16.7.2)  
  Install it with
   - Windows 10 SDK (10.0.18362.0)
   - C++ CMake tools for Windows
  
  For viewing md files in Visual Studio, install Markdown Editor Extension. In Visual Studio Extensions->Manage Extensions, and search for Markdown Editor. Click Download.
- [Boost binaries](https://sourceforge.net/projects/boost/files/boost-binaries/) (1.67.0 - *This exact version!*)
   - compiled with MSVC 14.1: `boost_1_67_0-msvc-14.1-64.exe`
   - install in default location `C:\local\boost_1_67_0`
- [NodeJS](https://nodejs.org/en/download/). Needed for *cenos-build-helper*
   - Choose LTS 64-bit version (12.18.3)
   - no need to check "Install Windows Build Tools" 

### Clone and prepare CENOS reporitories

**If you're authenticating using SSH with passphrase, Git Bash (or other Linux shell) usage is required!**
For some reason, git LFS is not showing prompt to enter passphrase for SSH key in cmd or PowerShell and because of that, authentication is failing on this step.

Using Git Bash resolves that issue.

- Prepare Git account
```shell script
git config --global user.name "YourNameHere"
git config --global user.password "YourPasswordHere"
```

**Note: From now on, replace `C:` with your directory (e.g. `D:`).**

- Clone cenos-backend repository
```shell script
cd C:\source
git clone https://gitlab.com/cenos/cenos-backend.git
```

- Clone and **initialize (!)** cenos-build-helper
```shell script
cd C:\source
git clone https://gitlab.com/cenos/cenos-build-helper.git
cd cenos-build-helper
npm install
npm link
```

- Clone cenos-ui repository
```shell script
cd C:\source
git clone https://gitlab.com/cenos/cenos-ui.git
```

 - Inside `cenos-ui/config` directory, create a copy of `environment.dev.example.js` and 
   rename it to `environment.dev.js`. 


**Inside the `environment.dev.js` file, update backend path to directory where you cloned your backend.**


### Build cenos-backend

- In Visual Studio, select **Open** → **Folder** and select the `C:\cenos-backend` directory. `CMake` should launch automatically.
- - In case of errors, you might have to open `CMakeSettings.json` and replace **line 16** with your Boost directory:
```json
"value": "C:\\local\\boost_1_67_0"
```
- From the top menu on Visual Studio, click **Build** → **Install cenos-backend**
- The executable file and all required DLLs will be placed in the `bin` directory
- The CENOS app configuration will be in `app` directory

If you want to run the backend without the UI, set env variable `CENOS_CONFIG` to the `app/ALL` directory   

### Build and start UI
**Do not try to update/force UI components! You will most likely end up with broken version dependencies!**

```script script
cd C:\source\cenos-ui
npm install
npm start
```

You can then select the app of your choice by entering the corresponding digit.

If cenos-ui does not change, you can run the previously-built version with
```
npm run app
```

`npm install` is needed initially. Afterwards, only if cenos-ui dependencies change, but won't harm if you do it more often.

Note: Some exceptions can be os-specific, in which case these may not be caught by some command-line interfaces (e.g. Git Bash, cygwin etc.). Using the default Command Prompt should work fine.

**Symptom:** you update cenos-ui, but it no longer builds.

### Build from command line

TODO: implement and document

### Debugging

Following steps are required to debug cenos-bacend:
1. [Install SWSC Extension to Chrome](#install-simple-web-socket-client-extension).
2. [Configure debugger settings](#configure-debugger-settings)
3. [Launch debug item in VS](#launch-debug-item-in-visual-studio)
4. [Use SWSC to send commands to backend](#use-swsc)
5. Debug as usual.


#### Install Simple Web Socket Client Extension

Find it [here](https://chrome.google.com/webstore/detail/simple-websocket-client/pfdhoblngboilpfeibdedpjgfnlcodoo?hl=en) and install to Chrome.

#### Configure debugger settings

Open configuration file launch.vs.json, located in a .vs folder in your project root. Add following configuration:
```
{
    "version": "0.2.1",
    "defaults": {},
    "configurations": [
      {
        "type": "default",
        "project": "CMakeLists.txt",
        "name": "cenos-debug-item",
        "args": [
          "9009"
        ],
        "env": { "PATH": "D:\\source\\cenos-backend\\bin" }
      }
    ]
}
```
args field contains port number that is passed as argument to cenos-backend.exe.
**Adjust env field so that it points to bin folder in cenos-backend project.**

Create a new `CENOS_CONFIG` enviroment variable with value: *`D:\source\cenos-backend\app\ALL`* in User variables as shown and then restart Visual Stuido, as it read the ENV variables on startup:

![](docs/CENOS_CONFIG.png)

Create `CENOS_APP` environment variable with value `INDUCTION` or `ANTENNAS`, depending on what product you are about to debug.

#### Launch debug item in Visual Studio. 
Select debug item in Visual Studio startup items and launch it (see screenshot below). This should start cenos-backend console. ![](docs/VS_launch_debug_item.png)

#### Use SWSC
- Lauch Simple Web Socket Client in Chrome ![](docs/WSClient.png)
- In URL type `ws://[::1]:9009/?id=gui`. Port number has to correspond to port number in args of launch.vs.json.
- Click Open. Following message should appear in backend console:
```
Incoming connection. ID gui is registered. Connection established.Incoming connection. ID gui is registered. Connection established.
```
- Copy the json request from UI console into SWSC. ![](docs/UI_console.png)
- Press Send. 

Now you should see any reply from backend in Message Log view.