Skip to content
Adam edited this page Jan 31, 2023 · 8 revisions

Windows 10 or Greater

Set-up

The following will need to be pre-installed:

  • Windows Subsystem for Linux WSL
  • Docker Desktop. You will likely need to make a Docker account
  • VcXsrv Windows X Server. This is the X11 window server. Make sure to check 'Fonts' at install. If only the command line interface is going to be used installation of this can be skipped

Quick Start

  1. Download the Dockerfile from the ESP-r repository
  2. Open Powershell and navigate to the directory where Dockerfile was saved
  3. Issue the following command: docker build -t espr .(The period at the end needs to be there). This will create an image of an Ubuntu OS with all dependencies needed to compile and run ESP-r
  4. Once the image is done building use the following command to create a new virtual environment from the image you just created: docker run -it espr /bin/bash. In Docker parlance this virtual environment is called a "container", and is built from the "image" which is essentially a template of a system configuration.
  5. You now have terminal access to the virtual machine. Go to the home directory (cd home) and clone a copy of the ESP-r source code: git clone https://github.com/ESP-rCommunity/ESP-rSource
  6. Navigate into the cloned repository (cd ESP-rSource) and use the following commands to compile the command-line interface version of ESP-r:
    • chmod u+x Install (This gives you permission to execute the Install bash script)
    • ./Install -d /usr/esru/devel/ --no_training --noX --gcc4 --silent
  7. Once compiling is complete test that the install has worked: /usr/esru/devel/bin/prj
  8. To exit out of the container simply type exit
  9. To re-access the container there are a couple steps. First we need the "name" of the container. You can either retrieve this from the Docker Desktop application or the command line. From Powershell type docker container ls -a. This will list all the containers currently on your local machine along with their statuses, what image they were built from, their names and IDs. Copy the container ID of the container you want to access. It the status is listed as Exited it'll have to be restarted using the following command: docker restart <CONTAINER_ID>. Once it's restarted use the command to access the terminal into the container: docker exec -it <CONTAINER_ID> /bin/bash

Running the Graphical Interface

To use the graphical interface VcXsrv Windows X Server needs to be installed and running prior accessing the container. Start the server on the Windows host machine using XLaunch and select the following options:

  1. Select "Multiple Windows" and set "Display Number" to "-1". Click "Next".
  2. Select "Start no client" then "Next".
  3. Make sure all boxes are checked including "Disable access control" then click "Next" and then "Finish".

Start a new container or re-connect to an existing one. Then use the following steps:

  1. Open "CMD" on Windows and run the command ipconfig.
  2. Copy the IPv4 Address. There may be a few so you have have to try them all until it works.
  3. In the container command line type export DISPLAY=<IP_ADDRESS>:0.0 where <IP_ADDRESS> is the IPv4 Address from step 3.
  4. Try launching prj.
    • You will need to have compiled ESP-r with the X11 libraries first. One way is ./Install -d /usr/esru/devel/ --xml --no_training --gcc4 --silent
    • prj can then be launched by /usr/esru/devel/bin/prj
  5. If it doesn't work try a different IP address and run the command in Step 3 again.
  6. To avoid having to run the export command every time it can be added to the .bashrc file:
    • Run the command nano ~/.bashrc
    • Somewhere near the bottom of the file add the line export DISPLAY=<IP_ADDRESS>:0.0
    • Save and close the file
    • Run source ~/.bashrc

Mapping Local Folder to Container

Mapping a folder on the host machine is a convenient way to transfer files between the host and container. The mapping is done at the time of container creation: docker run -ti -v <host_dir>:/locals espr /bin/bash where <host_dir> is the local directory. The folder /locals will be created in the container and map to the <host_dir>.

Developer Tools

The Data Display Debugger (ddd) is a useful tool for developing and testing code in ESP-r. This can be set up in the Docker container relatively easily. The X11 server will have to be running and the container will have to be configured per the instructions in the Running the Graphical Interface section. The steps are as follows:

  1. Within the container type the command apt-get update
  2. Then type the command apt-get install -y gdb ddd
  3. Compile ESP-r with debugging symbols: sudo bash Install -d /usr/esru/devel/ --no_training --extra-debug --gcc4 --silent
  4. Create a model that will call the part of the code you want to test. Make sure to create simulation presets. Navigate into the cfg folder.
  5. Use the following command to start the debugger: ddd /usr/esru/devel/bin/bps
  6. The debugging symbols will hopefully load. At the top on the menu click "File" then "Open Source". A new window will open listing the ESP-r source code file. Select the file(s) you wish to inspect.
  7. Place breakpoints at the critical spots in the code.
  8. Once all the breakpoints are in place run ESP-r. From the top menu click "Program" then "Run". An arguments window will pop up. In the "Run with Arguments" field type -file <MODEL>.cfg -p <PRESET> silent, where <MODEL> is the name of the model and <PRESET> is the name of the simulation preset. When ready click "Run".
  9. Usage of DDD is beyond the scope of this Wiki and the interested reader is directed to the DDD website for further details

Clone this wiki locally