docs: add installation steps (#18)

* docs: copy documents from Autoware.Auto

[#534] Adding specific troubleshooting steps to ade installation page.

Minor reorg of installation doc.

Resolve "Remove Atom from ADE"

Adding instructions for switching DDS vendors.

Resolve "Add Documentation to Installation Guide Regarding disabling NVidia GPUs"

Squashed 'src/external/autoware_auto_msgs/' changes from 56550efd..f40970ea

f40970ea Adding velocity_mps to VehicleControlCommand.

git-subtree-dir: src/external/autoware_auto_msgs
git-subtree-split: f40970ead34d36a695b432dc37accff9d67c17e2

Revert "Resolve "Apply Node Composition Using `rclcpp_components` to All Nodes" - pure_pursuit_nodes"

This reverts commit b0ec465b5d7385c8563fba75ff346d3e64e51d9d.

Added installation instructions without ade

Signed-off-by: Ignacio Montesino <[email protected]>

Rename and move documentation pages for clarity

Small fixes in installation instructions

Create new Building page which centralizes DDS vendor info, split up troubleshooting

Reviewer comments

Touch up docs on installing/building

[!808] Move index files for design docs and expand into README files

[!821] Fix numerours code highlighting and markup issues, add TOCs

- TOC still missing on design docs

[!828] Update documentation for demos for Foxy

[!835] Add AVP instructions to docs

Other improvements of the docs include

- table-of-contents generation fixed
- replace links to external markdown files with HTML. Not sure why doxygen doesn't complain in CI, it failed with version 1.8.13 in my ADE
- spell checking of numerous documents
- remove subtree doc

[!847] Add instructions for native arm64 ADE docker launch
 - Fix small typos and consistency in bash command style

[#888] Add doc information about checking out release specific branches

[861] Make code idiomatic for Foxy after 1.0 release

[#912] Make code snippet blocks consistent in documentation

[#1024] Add Point Type Adapter Node

[#1143] Document ROS_VERSION on non-ade install

ROS_VERSION needs to be set in order for the dependencies of the
tvm_vendor package to be correclty found.

Issue-Id: SCM-1400
Signed-off-by: Ambroise Vincent <[email protected]>
Change-Id: Id1c26514f1ba36688ac3a484decc69d4447cbd6e

[#1099]  Add ground_truth_detections package

update installation-ade.md to fix the wrong path

[#904] Move AVP Launch, Config, and Param Files into autoware_demos and Deprecate autoware_auto_avp_demo

[#1281] Add non-ade troubleshooting section on installation

[#1269] Enabling GPU acceleration by default in ade

fix link to avp_sensors.json in LGSVL installation docs

[#1358] Get AVP Demo to work with SVL Simulator 2021.3 Release

* update documents

* update documents

Signed-off-by: Kenji Miyake <[email protected]>

* fix

Signed-off-by: Kenji Miyake <[email protected]>

* add links

Signed-off-by: Kenji Miyake <[email protected]>

* fix link

Signed-off-by: Kenji Miyake <[email protected]>

Co-authored-by: Joshua Whitley <[email protected]>
Co-authored-by: Keisuke Shima <[email protected]>

docs/installation/autoware/.pages

@@ -1,4 +1,4 @@
 nav:
   - index.md
-  - local-installation.md
   - docker-installation.md
+  - source-installation.md

docs/installation/autoware/docker-installation.md

@@ -1,5 +1,131 @@
 # Docker installation
 
-!!! warning
+!!! info
 
-    Under Construction
+    Since this page explains Docker-specific information, it is recommended to see [Source installation](./source-installation.md) as well if you need detailed information.
+
+## Prerequisites
+
+- [Git](https://git-scm.com/)
+
+## How to set up a development environment
+
+1. Clone `autowarefoundation/autoware` and move to the directory.
+
+   ```bash
+   git clone https://github.com/autowarefoundation/autoware.git
+   ```
+
+2. Install the dependencies.
+
+   ```bash
+   ./setup-dev-env.sh docker
+   ```
+
+## How to set up a workspace
+
+1. Launch a Docker container
+
+   ```bash
+   rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest
+   ```
+
+   See [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md) for more advanced usage.
+
+   After that, move to the workspace in the container:
+
+   ```bash
+   cd autoware
+   ```
+
+2. Create the `src` directory and clone repositories into it.
+
+   ```bash
+   mkdir src
+   vcs import src < autoware.repos
+   ```
+
+3. Build the workspace.
+
+   ```bash
+   colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+   ```
+
+## How to update a workspace
+
+1. Update the Docker image.
+
+   ```bash
+   docker pull ghcr.io/autowarefoundation/autoware-universe:latest
+   rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest
+   ```
+
+2. Update the `.repos` file.
+
+   ```bash
+   cd autoware
+   git pull
+   ```
+
+3. Update the repositories.
+
+   ```bash
+   vcs import src < autoware.repos
+   vcs pull
+   ```
+
+4. Build the workspace.
+
+   ```bash
+   colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+   ```
+
+## Troubleshooting
+
+Here are solutions for a few specific errors:
+
+### cuda error: forward compatibility was attempted on non supported hw
+
+When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error:
+
+```bash
+docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:432: running prestart hook 0 caused \\\"error running hook: exit status 1, stdout: , stderr: nvidia-container-cli: initialization error: cuda error: forward compatibility was attempted on non supported hw\\\\n\\\"\"": unknown.
+ERROR: Command return non-zero exit code (see above): 125
+```
+
+This usually indicates that a new NVIDIA graphics driver has been installed (usually via `apt`) but the system has not yet been restarted. A similar message may appear if the graphics driver is not available, for example because of resuming after suspend.
+
+To fix this, restart your system after installing the new NVIDIA driver.
+
+## Tips
+
+### Non-native arm64 System
+
+This section describes a process to run `arm64` systems on `amd64` systems using [`qemu-user-static`](https://github.com/multiarch/qemu-user-static).
+
+Initially, your system is usually incompatible with `arm64` systems.
+To check that:
+
+```sh-session
+$ docker run --rm -t arm64v8/ubuntu uname -m
+WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested
+standard_init_linux.go:228: exec user process caused: exec format error
+```
+
+Installing `qemu-user-static` enables us to run `arm64` images on `amd64` systems.
+
+```sh-session
+$ sudo apt-get install qemu-user-static
+$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
+$ docker run --rm -t arm64v8/ubuntu uname -m
+WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested
+aarch64
+```
+
+To run Autoware's Docker images of `arm64` architecture, add the suffix `-arm64`.
+
+```sh-session
+$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:latest-arm64
+WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested
+root@5b71391ad50f:/autoware#
+```

docs/installation/autoware/index.md

@@ -1,5 +1,20 @@
 # Installation of Autoware
 
-!!! warning
+There are two ways to set up Autoware. Choose one according to your preference.
 
-    Under Construction
+## 1. Docker installation
+
+Docker can ensure that all developers in a project have a common, consistent development environment.
+It is recommended for beginners, light users, people who do not use Ubuntu.
+
+See [here](docker-installation.md) for the detailed steps.  
+Refer to [autowarefoundation/autoware/docker/README.md](https://github.com/autowarefoundation/autoware/blob/main/docker/README.md) as well.
+
+## 2. Source installation
+
+Source installation is for the cases where more granular control of the installation environment is needed.
+It is recommended for skilled users or people who want to customize the environment.  
+Note that some problems may occur depending on your local environment.
+
+See [here](source-installation.md) for the detailed steps.  
+Refer to the [autowarefoundation/autoware/README.md](https://github.com/autowarefoundation/autoware/blob/main/README.md) as well.

docs/installation/autoware/source-installation.md

@@ -0,0 +1,105 @@
+# Source installation
+
+## Prerequisites
+
+- [Ubuntu 20.04](https://releases.ubuntu.com/20.04/)
+- [Git](https://git-scm.com/)
+  - [Registering SSH keys to GitHub](https://github.com/settings/keys) is preferable.
+
+```bash
+sudo apt-get -y update
+sudo apt-get -y install git
+```
+
+## How to set up a development environment
+
+1. Clone `autowarefoundation/autoware` and move to the directory.
+
+   ```bash
+   git clone https://github.com/autowarefoundation/autoware.git
+   cd autoware
+   ```
+
+2. Install the dependencies.
+
+   We use [Ansible](https://www.ansible.com/) to simplify the steps.
+   Please see the Ansible playbooks and roles if you want to know exactly what packages are installed.
+
+   > Note: Before installing NVIDIA libraries, confirm and agree with the licenses.
+
+   - [CUDA](https://docs.nvidia.com/cuda/eula/index.html)
+   - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html)
+   - [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html)
+
+   ```bash
+   ./setup-dev-env.sh
+   ```
+
+## How to set up a workspace
+
+1. Create the `src` directory and clone repositories into it.
+
+   Autoware uses [vcstool](https://github.com/dirk-thomas/vcstool) to construct workspaces.
+
+   ```bash
+   cd autoware
+   mkdir src
+   vcs import src < autoware.repos
+   ```
+
+2. Install dependent ROS packages.
+
+   Autoware requires some ROS 2 packages in addition to the core components.
+   The tool `rosdep` allows an automatic search and installation of such dependencies.
+
+   ```bash
+   source /opt/ros/galactic/setup.bash
+   rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO
+   ```
+
+3. Build the workspace.
+
+   Autoware uses [colcon](https://colcon.readthedocs.io/en/released/index.html) to build workspaces.
+   Refer to the documentation for more advanced options.
+
+   ```bash
+   colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+   ```
+
+## How to update a workspace
+
+1. Update the `.repos` file.
+
+   ```bash
+   cd autoware
+   git pull
+   ```
+
+2. Update the repositories.
+
+   ```bash
+   vcs import src < autoware.repos
+   vcs pull
+   ```
+
+   For Git users:
+
+   - `vcs import` is similar to `git checkout`.
+     - Note that it doesn't pull from the remote.
+   - `vcs pull` is similar to `git pull`.
+     - Note that it doesn't switch branches.
+
+   Refer to the [official documentation](https://github.com/dirk-thomas/vcstool) for more information.
+
+3. Install dependent ROS packages.
+
+   ```bash
+   source /opt/ros/galactic/setup.bash
+   rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO
+   ```
+
+4. Build the workspace.
+
+   ```bash
+   colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+   ```

docs/installation/index.md

@@ -1,7 +1,36 @@
 # Installation
 
-!!! warning
+## Target platforms
 
-    Under Construction
+Autoware targets the platforms listed below. It may change in future versions of Autoware.
 
-## Supported platforms
+The Autoware Foundation provides no support on other platforms than those listed below.
+
+### Architecture
+
+- amd64
+- arm64
+
+### ROS version
+
+- ROS 2 Galactic (**active development**)
+- ROS 2 Humble (**will be supported in 2022**)
+
+Refer to [REP-2000](https://www.ros.org/reps/rep-2000.html) for the system dependencies.
+
+## Installation steps of Autoware
+
+See [here](autoware) for how to install Autoware.
+
+## Installation steps of tools for users
+
+Some other tools are required depending on the evaluation you want to do.
+For example, if you run E2E simulation, you need to install a simulator for that.
+
+See [here](tools-for-users) for how to install the tools.
+
+## Installation steps of tools for developers
+
+There are also tools and settings for developers, such as Shells or IDEs.
+
+See [here](tools-for-developers) for how to install the tools.