Skip to content
Snippets Groups Projects
Commit fa12c590 authored by Jonas Kvarnström's avatar Jonas Kvarnström
Browse files

Misc updates for installation instructions

parent 6b4b145e
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
README.md
+ 15
− 17
View file @ fa12c590
......@@ -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
......
doc/install.md
+ 54
− 47
View file @ fa12c590
......@@ -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
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment