From 6b4b145e76374f8a709c0d5b0c1fde852e48aa14 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Kvarnstr=C3=B6m?= <jonas.kvarnstrom@liu.se>
Date: Wed, 7 Apr 2021 09:25:57 +0200
Subject: [PATCH] Misc updates for installation instructions

---
 README.md      | 38 +++++++++++++++---------
 doc/install.md | 79 +++++++++++++++++++++++++++++---------------------
 2 files changed, 70 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index 718406a..a30d1d3 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,33 @@
 
 A number of development environments have been set up, adapted to different tasks.  
 
-Unlike the *tutorials*, the development environments cannot be
-entirely encapsulated in Docker images.  You will need your own Ubuntu
-Linux system for the actual development, though this system can run in
-a virtual machine (with some limitations).  You will also need to run
-ROS on this Linux system.  The development environment then provides
-many additional functionalities related to the core system, including
-those functionalities that are present in the tutorials.
-
-If you do not already have a ROS machine configured, or your main
-system uses a Linux version other than Ubuntu 18.04 / 20.04, then you
-can install the needed things following the instructions here:
+## Operating Systems
+
+Unlike the *tutorials*, these development environments cannot be
+entirely encapsulated in Docker images that can be executed on a 
+wider variety of operating systems.  For almost all development 
+purposes, you will also need:
+
+- An Ubuntu Linux 20.04 (or possibly 18.04) system for the actual development 
+  of your own software,
+  in particular when this software interfaces through ROS-based interfaces.
+  However, this does not necessarily have to be the "main" operating system 
+  on your computer:  Linux can be run in a virtual machine (with some 
+  limitations in terms of using 3D graphics).
+  
+- You will also (for almost all purposes) need to install and run ROS on this 
+  Linux system.  
+  
+The development environment then provides many additional functionalities 
+related to the core system, including those functionalities that are present 
+in the tutorials.
+
+If you do not already have an appropriate Ubuntu 20.04 (or 18.04) machine
+running ROS, please follow these installation instructions:
 
 - [Install Software on Local Machine or Virtual Machine](doc/install.md)
 
-++++++++++++++++++ The instructions above include things like ansible
-that you can't expect people to have just because they have a ROS
-machine ++++++++++++++++++BUT THERE ARE INSTRUCTION HOW TO INSTALL IT!!!+++++
+## Development Environments
 
 The basic idea is that the developer already has a Linux Ubuntu ROS installation 
 and then either checks out publicly available ROS package repos or
diff --git a/doc/install.md b/doc/install.md
index b328111..1cf3ec1 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -1,41 +1,51 @@
-# Install Instructions
+# Installing Linux and/or ROS
 
-Notice that ROS is only supported for Ubuntu LTS (that is 18.04 and
-20.04). We recommend to use 20.04. If using another version install
-18.04 or 20.04 as a virtual machine.
+Please make sure you have read the "Operating Systems" part of the [README](../README.md) first!
 
-It is possible to install an Ubuntu 20.04 virtual machine in
-Windows. Check the internet about this. But there will be isses with
-the 3D graphics. 2D graphics will work OK if you install an X-server
-on your Windows machine. For more information see:
+Also note that these instructions are for developers.  They do not necessarily explain every step in detail and have not necessarily been tested on every combination of 
+hardware, operating system, software setup and so on.  You are welcome to contact us for assistance in troubleshooting problems that may arise. 
 
-- https://gitlab.liu.se/lrs/symbicloud_docker_images/-/blob/master/doc/itn.md
+## Operating Systems and Development Environments 
 
-SHOULD THIS IMNFORMATION BE INCORPORATED HERE? OR OTHER INFORMATION?
+As mentioned in the [README](../README.md), you need an installation of Ubuntu 20.04 or 18.04 LTS.  Other versions, such as the more recent 20.10, are not supported by ROS.  We recommend **version 20.04**, which you can install in several ways:
 
-## Virtual Machine with Ubuntu 18.04 or 20.04
+- Install Ubuntu 20.04 as the main operating system on your computer, and stay on this version until version 22.04 is released and the development environments are updated.
 
-This section is instructions for if you run Ubuntu which is not 18.04 and 20.04.
+- Install Ubuntu 20.04 in a virtual machine such as VirtualBox, running on another version of Linux (such as the more recent Ubuntu 20.10, or another Linux distribution).  3D graphics will work, but will be slower???, especially if you use Gazebo??? +++++++++++ What is the precise meaning of "not recommended if Gazebo
+should be used because of 3D graphics requirements"?
 
-If you choose to use a virtual machine (not recommended if Gazebo
-should be used because of 3D graphics requirements) here are some
-information.
+- Install Ubuntu 20.04 in a virtual machine such as VirtualBox, running on a Windows machine.  This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server on the Windows machine.  There are some [initial instructions](https://gitlab.liu.se/lrs/symbicloud_docker_images/-/blob/master/doc/itn.md) for this.
 
-```bash
-sudo apt install gcc perl make   # to build guest addition kernel modules
-sudo apt install net-tools
-sudo apt install openssh-server
-```
+- Install Ubuntu 20.04 in a virtual machine such as VirtualBox, running on MacOS.  This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server.   +++++ Tested/untested? +++++
+
+## Virtual Machine: Ubuntu 18.04 or 20.04 on another Ubuntu version
+
+If you run another Ubuntu version than 18.04 or 20.04 on your computer, you can do the following to install a virtual machine.  These instructions are quite terse, as there exist plenty of descriptions on the web.
+
+- Install VirtualBox
+- Download [installation media](https://ubuntu.com/download/desktop) for Ubuntu 20.04.x LTS 
+- Start VirtualBox and create a new virtual machine
+- Install Ubuntu from the installation media that you downloaded
+- If and when Virtual box asks about the network:  You want a *bridged* network.
+- You need to do the following in the *virtual* machine:
+
+  ```bash
+  sudo apt install gcc perl make   # to build guest addition kernel modules
+  sudo apt install net-tools
+  sudo apt install openssh-server
+  ```
 
-Configure the network as bridged network.  ++++++++++++++++++
+- You also need to actually build and install the [Guest Additions](https://help.ubuntu.com/community/VirtualBox/GuestAdditions)
 
-## Installing Required Software on a Virtual Machine or an Ordinary Computer
+## Installing Required Software on your Development System
 
-Instructions here for Ubuntu 18.04 and Unbuntu 20.04.
+The following instructions need to be followed and executed on your *Development System*.
+
+By "Development System", we mean the **real computer or virtual machine** that runs **Ubuntu 18.04 or 20.04**, where you intend to do your development.
 
 ### Common
 
-Open a terminal window and execute the following command to update the list of packages available for your system:
+Open a terminal window (on your Development System as defined above!) and execute the following command to update the list of packages available for your system:
 ```bash
 sudo apt update
 ```
@@ -51,7 +61,7 @@ You can check what name it is by executing the following command to display the
 echo $USER
 ```
 
-Test if you can ssh into the machine without providing the password. It is necessary for the remaining steps described below.
+Test if you can ssh from the development system into itself without providing the password. It is necessary for the remaining steps described below.  
 ```bash
 ssh USER@localhost
 ```
@@ -59,11 +69,11 @@ If you are asked to enter the password, cancel the command (Ctrl+C) and execute
 ```bash
 ssh-copy-id -i USER@localhost
 ```
-If you don't have an ssh key generated on the machine yet, execute:
+If you don't have an SSH key generated on the development system yet, execute:
 ```bash
 ssh-keygen
 ```
-and repeat the previous step. You should now be able to login to the machine using: ```ssh USER@localhost```
+and repeat the previous step. You should now be able to login to the development system using ```ssh USER@localhost```
 
 Install the playbooks repo:
 ```bash
@@ -73,8 +83,7 @@ git clone https://gitlab.liu.se/lrs/lrs_playbooks.git
 
 ### Install Software using Ansible (Ubuntu 18.04)
 
-
-Install ansible:
+Install ansible on 18.04 (skip to the next section if you are running 20.04):
 ```bash
 ## sudo install --reinstall ca-certificates # Had to do this for the apt-add-repository to work
 sudo apt install software-properties-common
@@ -111,12 +120,15 @@ ansible-playbook -i hosts playbooks/wara_develop.yml -e user=${USER} -e install_
 
 ### Common Finishing Up
 
-Login and logout for the docker commands to work. Test with:
+Log in and log out for the docker commands to work. 
+
+Then test with:
+
 ```bash
 docker ps
 ```
 
-Add the following commands at the end of ```~/.bashrc``` file:
+Add the following commands at the end of the ```~/.bashrc``` file on your development system:
 ```bash
 export WORLD_ORIGIN_LAT=57.7605573519 
 export WORLD_ORIGIN_LON=16.6827607783
@@ -126,11 +138,12 @@ export WORLD_ORIGIN_ELEVATION=29.8
 source ${HOME}/wara_ws/devel/setup.bash
 export PATH=${HOME}/waraps/script:${PATH}
 ```
-These commands will take effect next time you open a new terminal window or login to the system.
+
+These commands will take effect next time you open a new terminal window or log in to the system.
 
 At this point your system now has the necessary software installed.
 
-You can use the following commands to test the 3D graphics hardware and driver setup on your system:
+You can use the following commands on the development system to test the 3D graphics hardware and driver setup on your system:
 
 ```bash
 glxgears
-- 
GitLab