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

---
 README.md      |  32 ++++++++--------
 doc/install.md | 101 ++++++++++++++++++++++++++-----------------------
 2 files changed, 69 insertions(+), 64 deletions(-)

diff --git a/README.md b/README.md
index a30d1d3..2466826 100644
--- a/README.md
+++ b/README.md
@@ -2,32 +2,30 @@
 
 A number of development environments have been set up, adapted to different tasks.  
 
+## General information
+
+Please 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. 
+
 ## 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.  
-  
+purposes, you will also need a "real" or virtual Ubuntu Linux  
+system, with ROS installed, for the actual development of your 
+own software.  
+
+Follow these installation instructions to install  
+ 
+ - [Install Software on Local Machine or Virtual Machine](doc/install.md)
+ 
+
+
 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)
-
 ## Development Environments
 
 The basic idea is that the developer already has a Linux Ubuntu ROS installation 
diff --git a/doc/install.md b/doc/install.md
index 1cf3ec1..a842172 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -2,48 +2,61 @@
 
 Please make sure you have read the "Operating Systems" part of the [README](../README.md) first!
 
-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 
+## General information
+
+Please 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. 
 
+
 ## Operating Systems and Development Environments 
 
-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:
+As mentioned in the [README](../README.md), you need an installation of Ubuntu 20.04 or 18.04 LTS (Long Term Support).  Other versions, such as the more recent 20.10, are not supported by ROS or by the software in the development environment.  We recommend **version 20.04**, which you can install either directly on your hardware (recommended) or in a virtual machine.
+
+### Terminology
+
+- **Main Operating System**:  The operating system that runs directly on your hardware.
+
+- **Development System**:  A *real computer* or *virtual machine* running *Ubuntu 18.04 or 20.04*, where you intend to do software development.
 
-- 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.
+### Alternatives
 
-- 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"?
+You can develop in one of the following ways:
 
-- 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.
+- Use Ubuntu 20.04 as the main operating system on your computer, and do not upgrade until the next long term support version is released (22.04), a new ROS version for Ubuntu 22.04 LTS is released, and a new version of the development environments.  This is the main alternative for many developers as the long term support versions provide a stable development system that minimizes the risk of incompatibility.
+
+- Use another version of Linux as the main operating system (for example a newer version of Ubuntu), with Ubuntu 20.04 installed in a virtual machine.  This is the best supported alternative to using Ubuntu 20.04 directly on your computer.  However, there can be issues with 3D graphics, in particular when new driver versions are released.  --- 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"?
+
+- 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, and we will do our best to help out in case of problems, but cannot guarantee that absolutely all aspects of a development environment will work as expected.
 
 - 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
+## Installing a Virtual Machine running Ubuntu 18.04 or 20.04
+
+*These instructions are quite terse, as there exist plenty of descriptions on the web.*
 
-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.
+If you do not run Ubuntu 20.04 (or 18.04) on your machine, you need to install a virtual machine.  You may use software such as [VirtualBox](https://www.virtualbox.org/), [Parallels](https://www.parallels.com/se/) or [VMWare Player](https://www.vmware.com/se/products/workstation-player.html) for this purpose.  We have mainly tested VirtualBox, as it is free.
+
+For VirtualBox:
 
 - 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:
+- You need to do the following in the *virtual* machine.  One reason is that you need to build the [Guest Addition](https://www.virtualbox.org/manual/ch04.html) modules that allow the "virtual Ubuntu" to communicate with the virtual machine software more efficiently, speed up graphics, allow the use of shared folders, and so on. 
 
   ```bash
   sudo apt install gcc perl make   # to build guest addition kernel modules
-  sudo apt install net-tools
-  sudo apt install openssh-server
+  sudo apt install net-tools openssh-server
   ```
 
-- You also need to actually build and install the [Guest Additions](https://help.ubuntu.com/community/VirtualBox/GuestAdditions)
+- You also need to actually *build and install* the [Guest Additions](https://help.ubuntu.com/community/VirtualBox/GuestAdditions).
 
 ## Installing Required Software on your Development System
 
-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.
+The following instructions need to be followed and executed on your *Development System*, regardless of whether this runs in a virtual machine or not.
 
-### Common
+### Setting up SSH
 
 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
@@ -75,58 +88,46 @@ ssh-keygen
 ```
 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
-sudo apt install git
-git clone https://gitlab.liu.se/lrs/lrs_playbooks.git
-```
+### Installing Ansible
+
+Some of the WARA PS software is installed using [Ansible Playbooks](https://docs.ansible.com/ansible/latest/index.html).
 
-### Install Software using Ansible (Ubuntu 18.04)
+If you use Ubuntu 18.04, you first need to do the following in order to get access to a repository containing the Ansible software:
 
-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
 sudo apt-add-repository --yes --update ppa:ansible/ansible
-sudo apt install ansible
 ```
 
-In the command below the value of the environment variable specifying
-the login name is used. You don't have to replace it.
+Regardless of Ubuntu version, continue as follows:
 
-Run playbook to install and update the wara developer programs. It can take several minutes to complete. Make sure you replace the last argument with the actual password of the root/administrator on this machine.
 ```bash
-cd lrs_playbooks
-git pull
-ansible-playbook -i hosts playbooks/wara_develop.yml -e user=${USER} -e install_user=${USER} -e ansible_sudo_pass=******
+sudo apt install ansible
 ```
 
-### Install Software using Ansible ( Ubuntu 20.04)
+### Installing software using Ansible Playbooks
+
+Clone our playbooks repo to get access to the actual playbooks for WARA PS:
 
-Install ansible:
 ```bash
-sudo apt install ansible
+sudo apt install git
+git clone https://gitlab.liu.se/lrs/lrs_playbooks.git
 ```
 
-In the command below the value of the environment variable specifying
-the login name is used. You don't have to replace it.
+Run the `wara_develop` playbook as follows to install and update the WARA PS developer software. It can take several minutes to complete.
+
+- In the command below the value of the environment variable specifying the login name is used. You don't have to replace it.
+
+- But make sure you replace the last argument with the actual password of the root/administrator on the development system.
 
-Run playbook to install and update the wara developer programs. It can take several minutes to complete. Make sure you replace the last argument with the actual password of the root/administrator on this machine.
 ```bash
 cd lrs_playbooks
 git pull
 ansible-playbook -i hosts playbooks/wara_develop.yml -e user=${USER} -e install_user=${USER} -e ansible_sudo_pass=******
 ```
 
-### Common Finishing Up
-
-Log in and log out for the docker commands to work. 
-
-Then test with:
-
-```bash
-docker ps
-```
+### Finishing Up
 
 Add the following commands at the end of the ```~/.bashrc``` file on your development system:
 ```bash
@@ -139,7 +140,13 @@ 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 log in to the system.
+Then log in and log out to the development system for the docker commands to work.  Test this with:
+
+```bash
+docker ps
+```
+
+++++ What should this say?  Is it just a test that nothing crashes or do you want to see something in particular?
 
 At this point your system now has the necessary software installed.
 
@@ -150,7 +157,7 @@ glxgears
 glmark2
 ```
 
-If the above commands execute without errors you can test that Gazebo works correctly on your system:
+If the above commands execute without errors you can test that Gazebo works correctly on your development system:
 
 ```bash
 roslaunch lrs_wara_gazebo gazebo.launch
-- 
GitLab