***************** About Singularity ***************** We are using Singularity_ to execute applications on the robots. With the provided image, you can test your code locally with simulation in the exact same environment as will be present on the real robot. The image we provide contains all dependencies to get started with the robot. If you want to use additional libraries in your own code, you can extend the image accordingly. .. _singularity_install: Install Singularity =================== We are using Singularity version 3.6. Other recent versions are probably also fine, however, we cannot guarantee compatibility for those. Unfortunately, most versions of Ubuntu still provide Singularity version 2.x in their official repositories. A newer version can be installed from source in this case. For this you may follow the `official installation instructions`_ or use the following, slightly simplified instructions (assuming you are working with Ubuntu). Install system dependencies:: $ sudo apt-get update && sudo apt-get install -y \ build-essential \ libssl-dev \ uuid-dev \ libgpgme11-dev \ squashfs-tools \ libseccomp-dev \ wget \ pkg-config \ git \ cryptsetup Get the required version of the Go compiler:: cd ~/Downloads # you can save it anywhere else, just adjust paths below wget https://dl.google.com/go/go1.13.linux-amd64.tar.gz tar -xzf go1.13.linux-amd64.tar.gz Note that it is only needed once for building singularity, so no need to install it permanently (we just add it to PATH temporarily for building, see below). Now download and unpack the singularity source:: wget https://github.com/sylabs/singularity/releases/download/v3.6.2/singularity-3.6.2.tar.gz tar -xzf singularity-3.6.2.tar.gz And finally build and install it:: export PATH=~/Downloads/go/bin:${PATH} # adjust path if you used a different directory cd singularity # the folder to which the singularity source was extracted ./mconfig cd builddir make sudo make install Now you should be able to use Singularity. You can test this, for example, by running ``singularity --version`` which should print "singularity version 3.6.2". For more information on how to use Singularity, see the `official documentation`_. .. _singularity_download_image: Download the Real Robot Challenge Image ======================================= There are different images for the different challenge phases. Make sure you are using the correct image for the phase you are working on. - `Download Singularity Image for Phase 2 `_ - `Download Singularity Image for Phase 3 `_ The image uses Ubuntu 18.04 and has all dependencies of the robot interface and the simulation already installed. For most of the libraries we use the default version provided through the official Ubuntu repositories. To explore the image and to check which libraries and which versions exactly are installed, you can run :: $ singularity shell path/to/realrobotchallenge.sif To open a shell inside the image. .. _singularity_extend_container: .. _singularity_custom_image: Add Custom Dependencies to the Container ======================================== The image we provide already includes everything needed to run the robot and the simulation. However, you may need additional libraries to use them in our own code, which are not yet present. In this case, you can create your own image which is based on our standard image but extends it with your additional dependencies. Note that you don't need to add your own code for the challenge to the image as this will be provided separately. So you only need to create a custom image if you want to install dependencies that are not yet available in the default image. Create the Custom Image ----------------------- To extend the image, create *definition file* like the following: :: # Specify the name of the base image below Bootstrap: localimage From: ./realrobotchallenge.sif %post # Put commands to install additional dependencies here. # Make sure everything runs automatically without human input (e.g. add # `-y` to automatically say "yes" below). apt-get install -y package_name See the official `Documentation for Definition Files`_ for all options in the definition file. Assuming you called your definition file ``user_image.def``, use the following command to build the image. Note that the base image (specified in the ``From:`` line) needs to be present in the directory in which you call the command. :: $ singularity build --fakeroot user_image.sif path/to/user_image.def .. warning:: To ensure that your custom image is compatible with our setup for executing the code, always use the official image as base and avoid overwriting existing libraries or applications with different versions. Upload the Custom Image ----------------------- To use your custom image on the robot, you will need to upload it and update your configuration. See :ref:`Configuration `. .. _Singularity: https://sylabs.io/guides/3.6/user-guide/ .. _official documentation: https://sylabs.io/guides/3.6/user-guide/index.html .. _Documentation for Definition Files: https://sylabs.io/guides/3.6/user-guide/definition_files.html .. _official installation instructions: https://sylabs.io/guides/3.6/user-guide/quick_start.html#quick-installation-steps