diff --git a/docs/installation/autoware/.pages b/docs/installation/autoware/.pages index e4ef1036208..3bda360633c 100644 --- a/docs/installation/autoware/.pages +++ b/docs/installation/autoware/.pages @@ -1,4 +1,4 @@ nav: - index.md - - local-installation.md - docker-installation.md + - source-installation.md diff --git a/docs/installation/autoware/docker-installation.md b/docs/installation/autoware/docker-installation.md index bb436018849..b3b23b469e8 100644 --- a/docs/installation/autoware/docker-installation.md +++ b/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# +``` diff --git a/docs/installation/autoware/index.md b/docs/installation/autoware/index.md index 292dd772203..1e060f96713 100644 --- a/docs/installation/autoware/index.md +++ b/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. diff --git a/docs/installation/autoware/local-installation.md b/docs/installation/autoware/local-installation.md deleted file mode 100644 index 06005ba2b7c..00000000000 --- a/docs/installation/autoware/local-installation.md +++ /dev/null @@ -1,5 +0,0 @@ -# Local installation - -!!! warning - - Under Construction diff --git a/docs/installation/autoware/source-installation.md b/docs/installation/autoware/source-installation.md new file mode 100644 index 00000000000..37e9e225c26 --- /dev/null +++ b/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 + ``` diff --git a/docs/installation/index.md b/docs/installation/index.md index 2fc0dd37325..cef81300758 100644 --- a/docs/installation/index.md +++ b/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.