Development Environment Setup

1. Clone the LiCoRICE repository.

   git clone https://github.com/bil/licorice.git
   cd licorice
   

2. Python virtualenv setup

   From the top-level LiCoRICE directory, run:

   ./install/env_setup.sh
   

3. Install pyenv and pyenv-virtualenv in your shell config. Bash users can use the following:

   cat ./install/pyenv_config.sh >> ~/.bashrc
   if [ -f "~/.bash_profile" ]; then
     cat ./install/pyenv_config.sh >> ~/.bash_profile
   else
     cat ./install/pyenv_config.sh >> ~/.profile
   fi
   source ~/.bashrc
   

4. Bind to the newly built virtualenv:

   pyenv activate licorice
   

   Or alternatively include a .python-version file in the top-level LiCoRICE directory containing licorice:

   echo licorice > .python-version
   

5. Ensure Correct Permissions

   To ensure you have the correct permissions, create a new limits file with sudo vi /etc/security/limits.d/licorice.conf and add these lines to ensure your user can run licorice. Replace <user> with the user you are using to run licorice.

   <user> - rtprio 95
   <user> - memlock unlimited
   <user> - nice -20
   

   Now log out and back in and you are set up for non-realtime licorice development and usage!

6. Optional - Modify BIOS settings and compile realtime kernel.

   1. Disable all ACPI and USB support in the BIOS of the target system.

      USB and ACPI features throw interrupts which can interfere with realtime performance.

      If USB support is needed for peripherals, enable only the minimum USB version necessary on as few ports as possible if such options in the BIOS exist.

   2. Compiling a realtime kernel is not a requirement to run LiCoRICE, but realtime performance is one of the central features of the platform. Without a realtime kernel, timing assurances are harder to deliver. Tick violations are more likely to occur as model complexity grows. For basic platform testing and evaluation, a realtime kernel is not necessary, but for any production deployments, realtime kernel compilation is strongly advised.

      The instructions for realtime kernel compilation here should be applied to a stock install of Ubuntu server 20.04 LTS.

      From the top-level LiCoRICE repository directory, run:

      LICO_ENABLE_USB=0 ./install/kernel_setup.sh
      

      This script will take from one to five hours to complete, depending on the speed and processor count of the system. Reboot to finish installation when notified. Any USB keyboards will not work after this point (USB support is disabled in this realtime kernel), use a PS/2 keyboard or ssh into the system.

      Note: if USB support is necessary (e.g., system requires realtime support for a USB peripheral), install the USB enabled kernel instead via LICO_ENABLE_USB=1 ./install/kernel_setup.sh instead. Enabling USB support will degrade system performance by a small amount, but may still fit within application tolerances. In general, a limited number of USB devices do not preclude consistently meeting 1ms ticks. Regardless, it is important to always verify timings for a given system deployment.

   3. The default installed kernel version is listed in the kernel_setup.sh script as KERNEL_RT_VERSION. Feel free to change this to fit your needs. For example, on an Ubuntu 18.04 system, you may wish to run:

      UBUNTU_VERSION=18.04 KERNEL_RT_VERSION=4.16.18-rt12 LICO_ENABLE_USB=0 ./install/kernel_setup.sh