p71924506
/
carla
mirror of https://github.com/carla-simulator/carla.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sergi e/p098 build (#2576) 

* new

* New iteration fixed style

* New iteration. Updated style.

* Style update.
This commit is contained in:
sergi.e 2020-03-11 15:42:41 +01:00 committed by GitHub
parent e4cc150a3c
commit fee8d620b4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 484 additions and 253 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Docs/build_docker.md
View File

@ -1,10 +1,15 @@
# Running CARLA in a Docker
* [__Docker installation__](#docker-installation)
* Docker CE
* NVIDIA-Docker2
* [__Running CARLA container__](#running-carla-container)
This tutorial is designed for:
* People that want to run CARLA without needing to install all dependencies
* Recommended solution to run multiple CARLA servers and perform GPU mapping
* People who don't need to render the full simulation (the server is headless)
* People that want to run CARLA without needing to install all dependencies.
* Recommended solution to run multiple CARLA servers and perform GPU mapping.
* People who don't need to render the full simulation (the server is headless).
This tutorial was tested in Ubuntu 16.04 and using NVIDIA 396.37 drivers.
This method requires a version of NVIDIA drivers >=390.
@ -17,20 +22,19 @@ This method requires a version of NVIDIA drivers >=390.
Docker requires sudo to run. Follow this guide to add users to the docker sudo
group <https://docs.docker.com/install/linux/linux-postinstall/>
#### Docker CE
### Docker CE
For our tests we used the Docker CE version.
To install Docker CE we recommend using [this tutorial][tutoriallink]
[tutoriallink]: https://docs.docker.com/install/linux/docker-ce/ubuntu/#extra-steps-for-aufs
#### NVIDIA-Docker2
### NVIDIA-Docker2
To install nvidia-docker-2 we recommend using the "Quick Start"
section from the [nvidia-dockers github](https://github.com/NVIDIA/nvidia-docker).
To install nvidia-docker-2 we recommend using the "Quick Start" section from the [nvidia-dockers github](https://github.com/NVIDIA/nvidia-docker).
---
## Getting it Running
## Running CARLA container
Pull the CARLA image.
@ -44,7 +48,7 @@ For selecting a version, for instance, version 0.8.2 (stable), do:
docker pull carlasim/carla:0.8.2
```
Running CARLA under docker:
Running CARLA under docker.
```sh
docker run -p 2000-2002:2000-2002 --runtime=nvidia -e --gpus all carlasim/carla:0.8.4
@ -53,12 +57,10 @@ docker run -p 2000-2002:2000-2002 --runtime=nvidia -e --gpus all carlasim/carla:
The `-p 2000-2002:2000-2002` argument is to redirect host ports for the docker container.
Use `--gpus '"device=<gpu_01>,<gpu_02>"'` to specify which GPUs should run CARLA. Take a look at this [NVIDIA documentation](https://github.com/NVIDIA/nvidia-docker) to learn other syntax options.
You can also pass parameters to the CARLA executable. With this you can chose the town and
select the port that is going to be used:
You can also pass parameters to the CARLA executable. With this you can chose the town and select the port that is going to be used.
```sh
docker run -p 2000-2002:2000-2002 --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=0 carlasim/carla:0.8.4 /bin/bash CarlaUE4.sh < Your list of parameters >
```
At the list of parameters do not forget to add `-world-port=<port_number>` so that CARLA runs on server mode
listening to the `<port_number>`
At the list of parameters do not forget to add `-world-port=<port_number>` so that CARLA runs on server mode listening to the `<port_number>`.

99
Docs/build_faq.md
View File

@ -1,6 +1,6 @@
# F.A.Q.
Some of the most common issues regarding CARLA installation and builds are listed hereunder. More issues can be found in the [GitHub issues][issuelink] for the project. In case a doubt is not listed here, take a look at the forum and feel free to post it.
Some of the most common issues regarding CARLA installation and builds are listed hereunder. Some more can be found in the [GitHub issues][issuelink] for the project. In case any doubt is not listed here, take a look at the forum and feel free to post it.
[issuelink]: https://github.com/carla-simulator/carla/issues?utf8=%E2%9C%93&q=label%3Aquestion+
<div class="build-buttons">
<p>
@ -17,9 +17,9 @@ CARLA forum</a>
Expected disk space to build CARLA.
</h5></summary>
It is advised to have at least 30/50GB. Building CARLA from source requires about 25GB of disk space, not counting Unreal Engine installation, which is quite a similar size.
It is advised to have at least 30/50GB. Building CARLA requires about 25GB of disk space, plus Unreal Engine, which is quite a similar size.
Unreal Engine on Linux requires much more disk space as it keeps all the intermediate files, take a look at [this thread](https://answers.unrealengine.com/questions/430541/linux-engine-size.html) about the matter.
Unreal Engine on Linux requires much more disk space as it keeps all the intermediate files. [This thread](https://answers.unrealengine.com/questions/430541/linux-engine-size.html) discusses the matter.
</details>
<!-- ======================================================================= -->
@ -28,8 +28,9 @@ CARLA forum</a>
Recommended hardware to run CARLA.
</h5></summary>
CARLA is a very performance demanding software, at the very minimum it needs for a 4GB GPU or even better, a dedicated GPU capable of running Unreal Engine. Take a look at [Unreal Engine's recommended hardware](https://wiki.unrealengine.com/Recommended_Hardware).
CARLA is a very performance demanding software. At the very minimum it needs for a 4GB GPU or, even better, a dedicated GPU capable of running Unreal Engine.
Take a look at [Unreal Engine's recommended hardware](https://wiki.unrealengine.com/Recommended_Hardware).
</details>
---
@ -40,7 +41,9 @@ CARLA forum</a>
"CarlaUE4.sh" script does not appear when downloading from GitHub.
</h5></summary>
There is no `CarlaUE4.sh` script in the source version of CARLA. Follow the [build instructions](build_linux.md) to build CARLA from source. To directly get the `CarlaUE4.sh` script, follow the [quick start instructions](start_quickstart.md).
There is no `CarlaUE4.sh` script in the source version of CARLA. Follow the [build instructions](build_linux.md) to build CARLA from source.
To run CARLA using `CarlaUE4.sh`, follow the [quick start installation](start_quickstart.md).
</details>
<!-- ======================================================================= -->
@ -49,14 +52,14 @@ CARLA forum</a>
"make launch" is not working on Linux.
</h5></summary>
Many different issues can be dragged during the build installation and finally show here, so here is a list of the most likely reasons why:
Many different issues can be dragged during the build installation, and show like this. Here is a list of the most likely reasons why.
* __Run Unreal Engine 4.22:__ Something may have failed when building Unreal Engine. Try running UE editor on its own and check out that it is the 4.22 release.
* __Download the assets:__ The server will not be able to run without the visual content, so this step is mandatory even when building CARLA for the first time. Go to the root CARLA folder and run the script to get the assets: `./Update.sh`
* __UE4_ROOT is not defined:__ The environment variable is not set. Remember to make it persistent session-wide by adding it to your `~/.bashrc` or `~/.profile`, otherwise it will need to be set for every new shell. Run `export UE4_ROOT=~/UnrealEngine_4.22` to set the variable this time. Make sure that the path leads to the UE 4.22 main folder.
* __Check dependencies:__ Confirm that everything was installed properly during the first steps of the process. Maybe one of the commands was skipped, unsuccessful or the dependencies were not suitable for the system.
* __Delete CARLA and clone it again:__ Just in case something went wrong. Delete your version of CARLA and try cloning or downloading and extracting it again. Then follow the steps from there.
* __Meet system requirements:__ Ubuntu version should be 16.04 or later. CARLA needs around 15GB of disk space and a dedicated GPU (or at least one with 4GB) to run.
* __Run Unreal Engine 4.22.__ Something may have failed when building Unreal Engine. Try running UE editor on its own and check out that it is the 4.22 release.
* __Download the assets.__ The server will not be able to run without the visual content. This step is mandatory.
* __UE4_ROOT is not defined.__ The environment variable is not set. Remember to make it persistent session-wide by adding it to the `~/.bashrc` or `~/.profile`. Otherwise it will need to be set for every new shell. Run `export UE4_ROOT=~/UnrealEngine_4.22` to set the variable this time.
* __Check dependencies.__ Make sure that everything was installed properly. Maybe one of the commands was skipped, unsuccessful or the dependencies were not suitable for the system.
* __Delete CARLA and clone it again.__ Just in case something went wrong. Delete CARLA and clone or download it again.
* __Meet system requirements.__ Ubuntu version should be 16.04 or later. CARLA needs around 15GB of disk space and a dedicated GPU (or at least one with 4GB) to run.
Other specific reasons for a system to show conflicts with CARLA may occur. Please, post these on the forum so the team can get to know more about them.
</details>
@ -70,9 +73,9 @@ Other specific reasons for a system to show conflicts with CARLA may occur. Plea
"CarlaUE4.exe" does not appear when downloading from GitHub.
</h5></summary>
There is no `CarlaUE4.exe` executable in the source version of CARLA. Follow the [build instructions](build_windows.md) to build CARLA from source. To directly get the `CarlaUE4.exe`, follow the [quick start instructions](start_quickstart.md).
</details>
There is no `CarlaUE4.exe` executable in the source version of CARLA. Follow the [build instructions](build_windows.md) to build CARLA from source. To directly get the `CarlaUE4.exe`, follow the [quick start instructions](start_quickstart.md).
</details>
<!-- ======================================================================= -->
<details>
@ -80,12 +83,12 @@ Other specific reasons for a system to show conflicts with CARLA may occur. Plea
CarlaUE4 could not be compiled. Try rebuilding it from source manually.
</h5></summary>
Something went wrong when trying to build CARLA. To know what happened, the build must be done using Visual Studio.
Something went wrong when trying to build CARLA. Rebuild using Visual Studio to discover what happened.
1. Go to `carla/Unreal/CarlaUE4` and right-click the `CarlaUE4.uproject`.
2. Click on __Generate Visual Studio project files__.
3. Open the file generated with Visual Studio 2017.
4. Compile the project with Visual Studio (shortcut is F7). The build will fail, but the issues found will be shown below.
__1.__ Go to `carla/Unreal/CarlaUE4` and right-click the `CarlaUE4.uproject`.
__2.__ Click on __Generate Visual Studio project files__.
__3.__ Open the file generated with Visual Studio 2017.
__4.__ Compile the project with Visual Studio. The shortcut is F7. The build will fail, but the issues found will be shown below.
</details>
<!-- ======================================================================= -->
@ -94,8 +97,9 @@ Something went wrong when trying to build CARLA. To know what happened, the buil
CMake error shows but CMake is properly installed.
</h5></summary>
This issue occurs when trying to use the _make_ command either to build the server or the client even though CMake is installed with an updated version and added to the environment path. The reason is that the issue is not really related with CMake but a conflict between Visual Studio versions.
Completely erase Visual Studio versions from the system and leave only the Visual Studio 2017 to make sure that everything works properly.
This issue occurs when trying to use the _make_ command either to build the server or the client. Even if CMake is installed, updated, and added to the environment path. There may be a conflict between Visual Studio versions.
Leave only VS2017 and completely erase the rest.
</details>
<!-- ======================================================================= -->
@ -104,9 +108,11 @@ Completely erase Visual Studio versions from the system and leave only the Visua
Error C2440, C2672: compiler version.
</h5></summary>
The build is not using the 2017 compiler due to conflict with other Visual Studio or Microsoft Compiler versions. Uninstall the other and rebuild again. If the problem still exists, it may be due to Visual Studio not being good at getting rid of itself. To completely clean Visual Studio from the computer go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`. This may need admin permissions.
The build is not using the 2017 compiler due to conflicts with other Visual Studio or Microsoft Compiler versions. Uninstall these and rebuild again.
To keep the other version of Visual Studio edit ```%appdata%\Unreal Engine\UnrealBuildTool\BuildConfiguration.xml``` adding the following lines:
Visual Studio is not good at getting rid of itself. To completely clean Visual Studio from the computer go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`. This may need admin permissions.
To keep other Visual Studio versions, edit ```%appdata%\Unreal Engine\UnrealBuildTool\BuildConfiguration.xml``` by adding the following lines.
```xml
<VCProjectFileGenerator>
@ -125,14 +131,14 @@ To keep the other version of Visual Studio edit ```%appdata%\Unreal Engine\Unrea
"make launch" is not working on Windows.
</h5></summary>
Many different issues can be dragged during the build installation and finally show here, so here is a list of the most likely reasons why:
Many different issues can be dragged during the build installation, and show like this. Here is a list of the most likely reasons why.
* __Restart the system:__ There are many installations going in the Windows build and it would be a great idea to give the system a chance to restart and make sure that everything is updated properly.
* __Run Unreal Engine 4.22:__ Something may have failed when building Unreal Engine. Try running UE editor on its own and make sure that it is the 4.22 release.
* __Download the assets:__ The server will not be able to run without the visual content, so this step is mandatory even when running CARLA for the first time.
* __Visual Studio 2017:__ If there are other versions of Visual Studio installed or recently uninstalled, conflicts may arise. To completely clean Visual Studio from the computer go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`.
* __Delete CARLA and clone it again:__ Just in case something went wrong. Delete your version of CARLA and try cloning or downloading and extracting it again. Then follow the steps from there.
* __Meet system requirements:__ CARLA needs around 30/50GB of disk space and a dedicated GPU (or at least one with 4GB) to run.
* __Restart the computer.__ There are many going on in the Windows build. Restart and make sure that everything is updated properly.
* __Run Unreal Engine 4.22.__ Something may have failed when building Unreal Engine. Run the Editor and check that 4.22 is being used.
* __Download the assets.__ The server will not be able to run without the visual content. This step is mandatory.
* __Visual Studio 2017.__ If there are other versions of Visual Studio installed or recently uninstalled, conflicts may arise. To completely clean Visual Studio from the computer go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`.
* __Delete CARLA and clone it again.__ Just in case something went wrong. Delete CARLA and clone or download it again.
* __Meet system requirements.__ CARLA needs around 30/50GB of disk space and a dedicated GPU (or at least one with 4GB) to run.
Other specific reasons for a system to show conflicts with CARLA may occur. Please, post these on the forum so the team can get to know more about them.
</details>
@ -142,7 +148,7 @@ Other specific reasons for a system to show conflicts with CARLA may occur. Plea
<summary><h5 style="display:inline">
Make is missing libintl3.dll or/and libiconv2.dll.
</h5></summary>
Download the [dependencies](http://gnuwin32.sourceforge.net/downlinks/make-dep-zip.php) and extract the _bin_ content into the __make__ installation path.
</details>
@ -152,10 +158,9 @@ Download the [dependencies](http://gnuwin32.sourceforge.net/downlinks/make-dep-z
Modules are missing or built with a different engine version.
</h5></summary>
This may happen, especially when building for the very first time. Just click on "Accept" to rebuild them.
Click on __Accept__ to rebuild them.
</details>
---
## Running CARLA
<!-- ======================================================================= -->
@ -164,9 +169,9 @@ This may happen, especially when building for the very first time. Just click on
Low FPS rate when running the server in Unreal Editor.
</h5></summary>
UE4 Editor goes to a low performance mode when out of focus. It can be disabled
in the editor preferences. Go to "Edit->Editor Preferences->Performance" and
disable the "Use Less CPU When in Background" option.
UE4 Editor goes to a low performance mode when out of focus.
Go to `Edit/Editor Preferences/Performance` in the editor preferences, and disable the "Use Less CPU When in Background" option.
</details>
@ -176,9 +181,9 @@ This may happen, especially when building for the very first time. Just click on
Can't run a script.
</h5></summary>
Some scripts have requirements that can be found in the files named __Requirements.txt__ in the same path as the script itself. Be sure to get these in order to run the script. The majority of them can simply be installed with a `pip install` command.
Some scripts have requirements. These are listed in files named __Requirements.txt__, in the same path as the script itself. Be sure to check these in order to run the script. The majority of them can be installed with a simple `pip` command.
Sometimes on Windows, scripts cannot run just using `script_name.py` in their directory. Try adding `python script_name.py`.
Sometimes on Windows, scripts cannot run with just `> script_name.py`. Try adding `> python script_name.py`, and make sure to be in the right directory.
</details>
@ -189,7 +194,7 @@ Sometimes on Windows, scripts cannot run just using `script_name.py` in their di
Connect to the simulator while running within Unreal Editor.
</h5></summary>
Press the "Play" button and wait until the scene is loaded. At that point, a Python client can connect to the simulator as with the standalone simulator.
Click on __Play__ and wait until the scene is loaded. At that point, a Python client can connect to the simulator as with the standalone simulator.
</details>
@ -199,7 +204,7 @@ Sometimes on Windows, scripts cannot run just using `script_name.py` in their di
Can't run CARLA neither binary nor source build.
</h5></summary>
One of the most common issues is that NVIDIA drivers are outdated in the system where CARLA is intended to run. Please make sure that this is not the case. If the issue is still unresolved, take a look at the [forum](https://forum.carla.org/) and feel free to post with the specific issue.
NVIDIA drivers may be outdated. Make sure that this is not the case. If the issue is still unresolved, take a look at the [forum](https://forum.carla.org/) and post the specific issue.
</details>
<!-- ======================================================================= -->
@ -207,9 +212,8 @@ Sometimes on Windows, scripts cannot run just using `script_name.py` in their di
<summary><h5 style="display:inline">
ImportError: DLL load failed: The specified module could not be found.
</h5></summary>
If this message appears when trying to run a script, one of the libraries needed has not been properly installed. As a work around, go to: `carla\Build\zlib-source\build`
Copy the file named `zlib.dll` in the directory of the script.
One of the libraries needed has not been properly installed. As a work around, go to `carla\Build\zlib-source\build`, and copy the file named `zlib.dll` in the directory of the script.
</details>
<!-- ======================================================================= -->
@ -217,7 +221,7 @@ Copy the file named `zlib.dll` in the directory of the script.
<summary><h5 style="display:inline">
ImportError: DLL load failed while importing libcarla: %1 is not a valid Win32 app.
</h5></summary>
A 32-bit Python version is creating conflicts when trying to run a script. Uninstall it and leave only the Python3 x64 required.
</details>
@ -229,7 +233,7 @@ A 32-bit Python version is creating conflicts when trying to run a script. Unins
Fatal error: 'version.h' has been modified since the precompiled header.
</h5></summary>
This happens from time to time due to Linux updates. There is a special target in the Makefile for this issue. It takes a long time but fixes the issue:
This happens from time to time due to Linux updates. There is a special target in the Makefile for this issue. It takes a long time but fixes the issue:
$ make hard-clean
$ make CarlaUE4Editor
@ -242,10 +246,9 @@ A 32-bit Python version is creating conflicts when trying to run a script. Unins
Create a binary version of CARLA.
</h5></summary>
In Linux, the recommended way is to run `make package` in the project folder. This method makes a packaged version of the project, including the Python API modules. This is the method used to make a release of CARLA for Linux.
In Linux, run `make package` in the project folder. The package will include the project, and the Python API modules.
Alternatively, it is possible to compile a binary version of CARLA within Unreal Editor.
Open the CarlaUE4 project, go to the menu "File -> Package Project", and select a platform. This takes a while, but it should generate a packaged version of CARLA to execute without Unreal Editor.
Alternatively, it is possible to compile a binary version of CARLA within Unreal Editor. Open the CarlaUE4 project, go to the menu `File/Package Project`, and select a platform. This may take a while.
</details>
---

222
Docs/build_linux.md
View File

@ -1,42 +1,105 @@
# Linux build
* [__Requirements__](#requirements):
* [__Linux build command summary__](#linux-build-command-summary)
* [__Requirements__](#requirements)
* System specifics
* Dependencies
* [__GitHub__](#github):
* [__GitHub__](#github)
* Create a GitHub account
* Install git
* Link GitHub and Unreal Engine
* [__Unreal Engine__](#unreal-engine):
* [__Unreal Engine__](#unreal-engine)
* Download UE4.22
* Build UE4.22
* [__CARLA build__](#carla-build):
* [__CARLA build__](#carla-build)
* Clone repository
* Get assets
* Set the environment variable
* make CARLA
The build process can be quite long and tedious. This documentation tries to make things clear and provides for a **[F.A.Q.](build_faq.md)** with solutions for the most common starting issues. However, the CARLA forum is open for anybody to post unexpected issues, doubts or suggestions. There is a specific section for installation issues on Linux. Feel free to login and become part of the community.
The build process can be quite long and tedious. The **[F.A.Q.](build_faq.md)** section contains the most common issues and solutions that appear during the installation. However, the CARLA forum is open for anybody to post unexpected issues, doubts or suggestions. There is a specific section for installation issues on Linux. Feel free to login and become part of the community.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>
---
## Linux build command summary
<details>
<summary> Show command lines to build on Linux</summary>
```sh
# Make sure to meet the minimum requirements and read the documentation to understand each step.
# Install dependencies.
sudo apt-get update &&
sudo apt-get install wget software-properties-common &&
sudo add-apt-repository ppa:ubuntu-toolchain-r/test &&
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key|sudo apt-key add - &&
sudo apt-add-repository "deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-7 main" &&
sudo apt-get update
# Additional dependencies for Ubuntu 18.04.
sudo apt-get install build-essential clang-7 lld-7 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user setuptools
# Additional dependencies for previous Ubuntu versions.
sudo apt-get install build-essential clang-7 lld-7 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng16-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user setuptools
# Change default clang version.
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/lib/llvm-7/bin/clang++ 170 &&
sudo update-alternatives --install /usr/bin/clang clang /usr/lib/llvm-7/bin/clang 170
# Get a GitHub and a UE account, and link both.
# Install git.
# Build Unreal Engine 4.22.
git clone --depth=1 -b 4.22 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.22
cd ~/UnrealEngine_4.22
./Setup.sh && ./GenerateProjectFiles.sh && make
# Open the UE Editor to check everything works properly.
cd ~/UnrealEngine_4.22/Engine/Binaries/Linux && ./UE4Editor
# Clone the CARLA repository.
git clone https://github.com/carla-simulator/carla
# Get the CARLA assets.
cd ~/carla
./Update.sh
# Set the environment variable.
export UE4_ROOT=~/UnrealEngine_4.22
# make the CARLA server and the CARLA client.
make launch
make PythonAPI
# Run an example script to test CARLA.
cd PythonAPI/examples
python3 spawn_npc.py
```
</details>
---
## Requirements
<h4>System specifics</h4>
* __Ubuntu 16.04 or later:__ Currently migrating to Ubuntu 18, but there is support up to Ubuntu 16.04.
* __30GB disk space:__ Installing all the software needed and CARLA itself will require quite a lot of space, especially Unreal Engine. Make sure to have around 30/50GB of free disk space.
* __An adequate GPU:__ CARLA aims for realistic simulations, so the server needs at least a 4GB GPU. A dedicated GPU is highly recommended for machine learning.
* __Two TCP ports and good internet connection:__ 2000 and 2001 by default. Be sure neither firewall nor any other application are blocking these.
### System specifics
* __Ubuntu 16.04 or later.__ Currently migrating to Ubuntu 18.
* __30GB disk space.__ Installing all the software needed and CARLA itself will require quite a lot of space, especially Unreal Engine. Make sure to have around 30/50GB of free disk space.
* __An adequate GPU.__ CARLA aims for realistic simulations, so the server needs at least a 4GB GPU. A dedicated GPU is highly recommended for machine learning.
* __Two TCP ports and good internet connection.__ 2000 and 2001 by default. Be sure neither the firewall nor any other application block these.
#### Dependencies
### Dependencies
CARLA needs many dependencies to run. Some of them are built automatically during this process, such as *Boost.Python*. Others are binaries that should be installed before starting the build (*cmake*, *clang*, different versions of *Python* and much more). In order to do so, run the commands below in a terminal window.
@ -50,22 +113,22 @@ sudo apt-get update
```
!!! Important
The following commands differ depending on Ubuntu version. While the only change is `libpng16-dev` becoming `libpng-dev`, the full set of commands is here twice to ease the copy.
The following commands differ depending on the Ubuntu version. While the only change is `libpng16-dev` becoming `libpng-dev`, the full set of commands is here twice to ease the copy.
__Ubuntu 18.04__:
__Ubuntu 18.04__.
```sh
sudo apt-get install build-essential clang-7 lld-7 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user setuptools
```
__Previous Ubuntu__ versions:
__Previous Ubuntu__ versions.
```sh
sudo apt-get install build-essential clang-7 lld-7 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng16-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user setuptools
```
Finally, to avoid compatibility issues between Unreal Engine and the CARLA dependencies, it is recommended to use the same compiler version and C++ runtime library to compile everything. The CARLA team uses clang-7 and LLVM's libc++. Change your default clang version to compile Unreal Engine and the CARLA dependencies.
To avoid compatibility issues between Unreal Engine and the CARLA dependencies, it is recommended to use the same compiler version and C++ runtime library to compile everything. The CARLA team uses clang-7 and LLVM's libc++. Change the default clang version to compile Unreal Engine and the CARLA dependencies.
```sh
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/lib/llvm-7/bin/clang++ 170 &&
@ -75,58 +138,59 @@ sudo update-alternatives --install /usr/bin/clang clang /usr/lib/llvm-7/bin/clan
---
## GitHub
First of all, a [GitHub](https://github.com/) account will be needed, as CARLA content is organized in different repositories in there. Also, [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) will be used in this build guide when facilitating commands to be run in terminal.
A [GitHub](https://github.com/) account will be needed, as CARLA content is organized in different repositories in there. Also, [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) will be used in this build guide when facilitating commands to be run in terminal.
In order to access the Unreal Engine repositories, which are set to private, create an [Unreal Engine](https://www.unrealengine.com/en-US/feed) account and connect it to a GitHub account. To do so, there is a section in Unreal Engine's profile settings under the name of __Connected accounts__. [Here](https://www.unrealengine.com/en-US/blog/updated-authentication-process-for-connecting-epic-github-accounts) is a brief explanation just in case.
---
## Unreal Engine
The current version of CARLA runs on __Unreal Engine 4.22__ only, so the following steps will be downloading this version and building it. The path is irrelevant, but for the sake of this tutorial, installation will be done under `~/UnrealEngine_4.22`. If the path chosen differs, remember to change it accordingly when running the commands on terminal.
The process described below can be found in this [complete guide](https://docs.unrealengine.com/en-US/Platforms/Linux/BeginnerLinuxDeveloper/SettingUpAnUnrealWorkflow/index.html) on how to build Unreal Engine on Linux. It can be consulted if preferred, but remember though that CARLA will need the __4.22 release__, not the latest.
The current version of CARLA runs on __Unreal Engine 4.22__ only. The path is irrelevant, but for the sake of this tutorial, installation will be done under `~/UnrealEngine_4.22`. If the path chosen differs, remember to change it accordingly when running the commands on terminal.
Clone the content for Unreal Engine 4.22 in a local computer:
!!! Note
Alternatively, there is this [guide](https://docs.unrealengine.com/en-US/Platforms/Linux/BeginnerLinuxDeveloper/SettingUpAnUnrealWorkflow/index.html) to build UE on Linux. When consulting it, remember that CARLA will need the __4.22 release__, not the latest.
Clone the content for Unreal Engine 4.22 in a local computer.
```sh
git clone --depth=1 -b 4.22 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.22
```
Get into said folder. Remember, this is the path where you cloned UE4.22:
Get into said folder. Remember, this is the path where UE4.22 has been cloned.
```sh
cd ~/UnrealEngine_4.22
```
Run the commands necessary to make the build.
Make the build.
```sh
./Setup.sh && ./GenerateProjectFiles.sh && make
```
Unreal Engine should be installed in the system. To try running it go to _Engine/Binaries/Linux_ folder and run _the UE4Editor.sh_:
Unreal Engine should be installed in the system. Run `Engine/Binaries/Linux/UE4Editor.sh` to open the Editor and check it out.
```sh
cd ~/UnrealEngine_4.22/Engine/Binaries/Linux && ./UE4Editor
```
If anything goes wrong, it is related with Unreal Engine and there is not much CARLA can do about it. However, checking the guide mentioned above or visiting the [build documentation](https://wiki.unrealengine.com/Building_On_Linux) provided by Unreal Engine could be helpful.
In case something went wrong, it is related with Unreal Engine There is not much CARLA can do about it. However, the [build documentation](https://wiki.unrealengine.com/Building_On_Linux) provided by Unreal Engine may be helpful.
---
## CARLA build
The system should be ready to start building CARLA. Just for clarity, a brief summary so far:
The system should be ready to start building CARLA. Just for clarity, a brief summary so far.
* Minimum technical requirements to run CARLA are suitable.
* Dependencies have been properly installed.
* GitHub account is ready.
* Unreal Engine 4.22 runs smooth.
* Minimum technical requirements to run CARLA are suitable.
* Dependencies have been properly installed.
* GitHub account is ready.
* Unreal Engine 4.22 runs smooth.
!!! Note
Optionally you can download aria2 (with `sudo apt-get install aria2`) so the following commands run a bit faster.
Downloading aria2 with `sudo apt-get install aria2` will speed up the following commands.
#### Clone repository
### Clone repository
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://github.com/carla-simulator/carla" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
<a href="https://github.com/carla-simulator/carla" target="_blank" class="btn btn-neutral" title="Go to the CARLA repository">
<span class="icon icon-github"></span> CARLA repository</a>
</p>
</div>
The project can be found in GitHub. Either download and extract it or clone it on the local computer using the following command line:
The official repository of the project. Either download and extract it or clone it using the following command line.
```sh
git clone https://github.com/carla-simulator/carla
@ -135,71 +199,101 @@ git clone https://github.com/carla-simulator/carla
Now the latest content for the project, known as `master` branch in the repository, has been copied in local.
!!! Note
The `master` branch contains the latest fixes and features. Stable code is inside the `stable` branch, and it can be built by changing the branch. The same goes for previous CARLA releases. Always remember to check the current branch in git with `git branch`.
The `master` branch contains the latest fixes and features. Stable code is inside the `stable` and previous CARLA versions have their own branch. Always remember to check the current branch in git with the command `git branch`.
#### Get assets
### Get assets
Only the assets package is yet to be donwloaded. These are stored separately to make the repository a bit lighter. CARLA cannot be built without the assets. There is a script that downloads and extracts the latest content version. The package is >3GB, so downloading it may take some time.
Only the assets package, the visual content, is yet to be donwloaded. These are stored separately to make the repository a bit lighter. CARLA cannot be built without the assets, so there is a script that downloads and extracts the latest content version (this package is >3GB, it might take some time depending on internet connection).
Get into the root carla folder. The path should correspond with the repository just cloned:
```sh
cd ~/carla
```
Run the script to get the assets:
Run the script to get the assets.
```sh
./Update.sh
```
!!! Important
To get the assets still in development visit the [Update CARLA](build_update.md#get-development-assets) page and read __Get development assets__.
To get the assets currently in development, visit [Update CARLA](build_update.md#get-development-assets) and read __Get development assets__.
#### Set the environment variable
### Set the environment variable
For CARLA to find the Unreal Engine 4.22 installation folder, an environment variable needs to be set.
This is necessary for CARLA to find the Unreal Engine 4.22 installation folder.
```sh
export UE4_ROOT=~/UnrealEngine_4.22
```
This variable should be added to `~/.bashrc` or `~/.profile` to set it persistently session-wide. Otherwise, it will only be accessible for current shell.
The variable should be added to `~/.bashrc` or `~/.profile` to be set persistently session-wide. Otherwise, it will only be accessible from the current shell.
#### make CARLA
### make CARLA
The last step is to finally build CARLA. There are different `make` commands to build the different modules. All of them run in the root CARLA folder:
The last step is to finally build CARLA. There are different `make` commands to build the different modules. All of them run in the root CARLA folder.
!!! Warning
Make sure to run __make launch__ to prepare the server and __make PythonAPI__ for the client.
Alternativelly __make libcarla__ will prepare the CARLA library to be imported anywhere.
Alternatively __make libcarla__ will prepare the CARLA library to be imported anywhere.
* __launch__ will compile the server simulator and launch it in Unreal Engine. Press **Play** to start the spectator view and close the editor window to exit. Camera can be moved with WASD keys and rotated by clicking the scene while moving the mouse around:
* __make launch__ compiles the server simulator and launches Unreal Engine. Press **Play** to start the spectator view and close the editor window to exit. Camera can be moved with `WASD` keys and rotated by clicking the scene while moving the mouse around.
```sh
make launch
```
The project may ask to build other instances such as `UE4Editor-Carla.dll` the first time. Agree in order to open the project. Also, during the first launch Unreal Editor may show warnings regarding shaders and mesh distance fields. These take some time to be loaded and the city will not show properly until then.
The project may ask to build other instances such as `UE4Editor-Carla.dll` the first time. Agree in order to open the project. During the first launch, the editor may show warnings regarding shaders and mesh distance fields. These take some time to be loaded and the city will not show properly until then.
* __make PythonAPI__ compiles the API client, necessary to grant control over the simulation. It is only needed the first time. Remember to run it again when updating CARLA. Scripts will be able to run after this command is executed. The following example will spawn some life into the town.
* __PythonAPI__ will compile the API client, necessary to grant control over the simulation. It is only needed the first time (remember to run it again when the CARLA code is updated). After building it, scripts can run. The following example will spawn some life into the city:
```sh
make PythonAPI && cd PythonAPI/examples && python3 spawn_npc.py
```
!!! Note
If the simulation is running at very low FPS rates, open the UE4.22 editor and go to "Edit>Editor preferences>Performance" and disable: **Use less CPU when in background**.
!!! Important
If the simulation is running at very low FPS rates, go to `Edit/Editor preferences/Performance` in the UE editor and disable __Use less CPU when in background__.
Now everything is ready to go and CARLA has been successfully built. Here is a brief summary of the most useful `make` commands available:
Now CARLA is ready to go. Here is a brief summary of the most useful `make` commands available.
| Command | Description |
| --- | --- |
| `make help` | Prints all available commands. |
| `make launch` | Launches CARLA Editor. |
| `make PythonAPI` | Builds the CARLA client. |
| `make package` | Builds CARLA and creates a packaged version for distribution. |
| `make clean` | Deletes all the binaries and temporals generated by the build system. |
| `make rebuild` | make clean and make launch both in one command. |
<table class ="defTable">
<thead>
<th>Command</th>
<th>Description</th>
</thead>
<tbody>
<td>
<code>make help</code> </td>
<td>Prints all available commands.</td>
</tr>
<tr>
<td><code>make launch</code></td>
<td>Launches CARLA server in Editor window.</td>
</tr>
<tr>
<td><code>make PythonAPI</code></td>
<td>Builds the CARLA client.</td>
</tr>
<tr>
<td><code>make package</code></td>
<td>Builds CARLA and creates a packaged version for distribution.</td>
</tr>
<tr>
<td><code>make clean</code></td>
<td>Deletes all the binaries and temporals generated by the build system.</td>
</tr>
<tr>
<td><code>make rebuild</code></td>
<td>make clean and make launch both in one command.</td>
</tbody>
</table>
---
<br>
Keep reading this section to learn more about how to update CARLA, the build itself and some advanced configuration options. Otherwise, visit the __First steps__ section to learn about CARLA:
Keep reading this section to learn how to update the build or take some first steps in CARLA.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="../core_concepts" target="_blank" class="btn btn-neutral" title="Start reading First steps">
Go to First steps</a>
<a href="../core_concepts" target="_blank" class="btn btn-neutral" title="Learn about CARLA core concepts">
Go to __First steps__</a>
</p>
<p>
<a href="../build_update" target="_blank" class="btn btn-neutral" title="Learn how to update the build">
Update CARLA</a>
</p>
</div>

75
Docs/build_system.md
View File

@ -1,22 +1,22 @@
# Build system
* [__Setup__](#setup)
* [__LibCarla__](#libcarla)
* [__CarlaUE4 and Carla plugin__](#carlaue4-and-carla-plugin)
* [__PythonAPI__](#pythonapi)
> _This document is a work in progress, only the Linux build system is taken into account here._
The most challenging part of the setup is to compile all the dependencies and
modules to be compatible with a) Unreal Engine in the server-side, and b) Python
in the client-side.
The most challenging part of the setup is to compile all the dependencies and modules to be compatible with a) Unreal Engine in the server-side, and b) Python in the client-side.
The goal is to be able to call Unreal Engine's functions from a separate Python
process.
The goal is to be able to call Unreal Engine's functions from a separate Python process.
![modules](img/modules.png)
In Linux, we compile CARLA and all the dependencies with clang-7.0 and C++14
standard. We however link against different runtime C++ libraries depending on
where the code going to be used, since all the code that is going to be linked
with Unreal Engine needs to be compiled using `libc++`.
In Linux, we compile CARLA and all the dependencies with clang-7.0 and C++14 standard. We however link against different runtime C++ libraries depending on where the code going to be used, since all the code that is going to be linked with Unreal Engine needs to be compiled using `libc++`.
#### Setup
---
## Setup
Command
@ -31,7 +31,8 @@ Get and compile dependencies
* boost-1.72.0 (headers and boost_python for libstdc++)
* googletest-1.8.1 (with libc++)
#### LibCarla
---
## LibCarla
Compiled with CMake (minimum version required CMake 3.9).
@ -43,20 +44,41 @@ make LibCarla
Two configurations:
| | Server | Client |
|-----------------|--------------|-----------|
| **Unit tests** | yes | no |
| **Requires** | rpclib, gtest, boost | rpclib, boost
| **std runtime** | LLVM's `libc++` | Default `libstdc++` |
| **Output** | headers and test exes | `libcarla_client.a` |
| **Required by** | Carla plugin | PythonAPI |
<table class ="defTable">
<thead>
<th> </th>
<th>Server</th>
<th>Client</th>
</thead>
<tbody>
<td><b>Unit tests<b></td>
<td> Yes </td>
<td> No </td>
<tr>
<td><b>Requirements</b></td>
<td> rpclib, gtest, boost </td>
<td> rpclib, boost </td>
<tr>
<td><b>std runtime</b></td>
<td> LLVM's <code>libc++</code></td>
<td> Default <code>libstdc++</code> </td>
<tr>
<td><b>Output</b></td>
<td> headers and test exes </td>
<td> <code>ibcarla_client.a</code></td>
<tr>
<td><b>Required by</b></td>
<td> Carla plugin </td>
<td> PythonAPI </td>
</tbody>
</table>
<br>
#### CarlaUE4 and Carla plugin
---
## CarlaUE4 and Carla plugin
Both compiled at the same step with Unreal Engine build tool. They require the
`UE4_ROOT` environment variable set.
Both compiled at the same step with Unreal Engine build tool. They require the `UE4_ROOT` environment variable set.
Command
@ -70,10 +92,10 @@ To launch Unreal Engine's Editor run
make launch
```
#### PythonAPI
---
## PythonAPI
Compiled using Python's `setuptools` ("setup.py"). Currently requires the
following to be installed in the machine: Python, libpython-dev, and
Compiled using Python's `setuptools` ("setup.py"). Currently requires the following to be installed in the machine: Python, libpython-dev, and
libboost-python-dev; both for Python 2.7 and 3.5.
Command
@ -87,8 +109,7 @@ It creates two "egg" packages
* `PythonAPI/dist/carla-X.X.X-py2.7-linux-x86_64.egg`
* `PythonAPI/dist/carla-X.X.X-py3.5-linux-x86_64.egg`
This package can be directly imported into a Python script by adding it to the
system path
This package can be directly imported into a Python script by adding it to the system path.
```python
#!/usr/bin/env python
@ -104,7 +125,7 @@ import carla
# ...
```
or installed with `easy_install`
Alternatively, it can be installed with `easy_install`
```sh
easy_install2 --user --no-deps PythonAPI/dist/carla-X.X.X-py2.7-linux-x86_64.egg

112
Docs/build_update.md
View File

@ -1,36 +1,73 @@
# Update CARLA
* [__Get lastest binary release__](#get-latest-binary-release)
* [__Update Linux and Windows build__](#update-linux-and-windows-build)
* Clean the build
* Pull from origin
* Download the assets
* Launch the server
* [__Get development assets__](#get-development-assets)
* [__Update commands summary__](#update-commands-summary)
* [__Get the lastest binary release__](#get-latest-binary-release)
* [__Update Linux and Windows build__](#update-linux-and-windows-build)
* Clean the build
* Pull from origin
* Download the assets
* Launch the server
* [__Get development assets__](#get-development-assets)
To post unexpected issues, doubts or suggestions, feel free to login in the CARLA forum.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
CARLA forum</a>
</p>
</div>
---
## Update commands summary
<details>
<summary> Show command lines to update CARLA</summary>
```sh
# Update a CARLA packaged release.
# 1. Delete the current one.
# 2. Follow the Quick start installation to get the one desired.
# Update Linux build.
git checkout master
make clean
git pull origin master
./Update.sh
# Update Windows build.
git checkout master
make clean
git pull origin master
# Erase the content in `Unreal\CarlaUE4\Content\Carla`.
# Go to `\Util\ContentVersions.txt`.
# Download the latest content.
# Extract the new content in `Unreal\CarlaUE4\Content\Carla`.
# Get development assets.
# Delete the `/Carla` folder containing previous assets.
# Go to the main carla folder.
git clone https://bitbucket.org/carla-simulator/carla-content Unreal/CarlaUE4/Content/Carla
```
</details>
---
## Get latest binary release
Binary releases are prepackaged and thus, tied to a specific version of CARLA. In order to get the latest, erase the previous one and follow the procedure stated in the [quick start installation](start_quickstart.md). In the CARLA repository, releases are listed in __Development__ and there is also a highly experimental __Nightly build__ containing the current state of CARLA up to date:
Binary releases are prepackaged and thus, tied to a specific version of CARLA. To get the latest, erase the previous and follow the [quick start installation](start_quickstart.md) to get the one desired.
Releases are listed in __Development__ in the CARLA repository. There is also a highly experimental __Nightly build__ containing the current state of CARLA up to date.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://github.com/carla-simulator/carla/blob/master/Docs/download.md" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
<span class="icon icon-github"></span> Get the latest release</a>
<a href="https://github.com/carla-simulator/carla/blob/master/Docs/download.md" target="_blank" class="btn btn-neutral" title="Go to the list of CARLA releases">
<span class="icon icon-github"></span> Get releases</a>
</p>
<!-- Nightly build button -->
<p>
<a href="http://carla-releases.s3.amazonaws.com/Linux/Dev/CARLA_Latest.tar.gz" target="_blank" class="btn btn-neutral" title="Go to the nightly CARLA build">
<span class="icon fa-cloud-download"></span> Get the nightly build</a>
@ -40,42 +77,47 @@ Binary releases are prepackaged and thus, tied to a specific version of CARLA. I
---
## Update Linux and Windows build
!!! Important
Make sure to be in the local `master` branch before updating to then merge or rebase the changes to other branches.
Make sure to be in the local `master` branch before the update. Then, merge or rebase the changes to other branches and solve possible conflicts.
The process of updating is quite similar and straightforward for both platforms:
#### Clean the build
Go to the CARLA main directory and delete binaries and temporals generated by previous build:
```sh
git checkout master
```
### Clean the build
Go to the main CARLA folder and delete binaries and temporals generated by the previous build.
```sh
make clean
```
#### Pull from origin
### Pull from origin
Get the current version from `master` in the CARLA repository:
Get the current version from `master` in the CARLA repository.
```sh
git pull origin master
```
#### Download the assets
__Linux:__
### Download the assets
__Linux.__
```sh
./Update.sh
```
__Windows:__
- Erase the previous content in `Unreal\CarlaUE4\Content\Carla`.
- Go to `\Util\ContentVersions.txt`.
- Download the content for `latest`.
- Extract the new content in `Unreal\CarlaUE4\Content\Carla`.
__Windows.__
__1.__ Erase the previous content in `Unreal\CarlaUE4\Content\Carla`.
__2.__ Go to `\Util\ContentVersions.txt`.
__3.__ Download the content for `latest`.
__4.__ Extract the new content in `Unreal\CarlaUE4\Content\Carla`.
!!! Note
In order to work with the current content used by developers in the CARLA team, follow the get development assets section right below this one.
In order to work with that the CARLA team is devleoping, go to __get development assets__ below.
#### Launch the server
### Launch the server
Run the server in spectator view to make sure that everything worked properly.
Run the editor with the spectator view to be sure that everything worked properly:
```sh
make launch
```
@ -83,16 +125,18 @@ make launch
---
## Get development assets
The 3D assets, models, and maps have also a [public git repository][contentrepolink] where the CARLA team regularly pushes latest updates. However, using this version of the content is only recommended to developers, as it may contain unfinished maps and/or models.
The CARLA team works with assets still in development. These models and maps have a [public git repository][contentrepolink] where the CARLA team regularly pushes latest updates. Assets are still unfinished, using them is only recommended for developers.
In order to handle this repository it is highly recommended to install [git-lfs][gitlfslink], as it works faster with large binary files, and these are modified regularly. To clone this repository **go to the main CARLA directory** and run the following command:
In order to handle this repository it is advisted to install [git-lfs][gitlfslink]. The repository is modified regularly, and git-lfs works faster with large binary files.
To clone the repository, __go to the main CARLA directory__ and run the following command.
```sh
git clone https://bitbucket.org/carla-simulator/carla-content Unreal/CarlaUE4/Content/Carla
```
!!! Warning
Delete the `/Carla` folder containing the assets before using the previous command. Otherwise, an error will show.
Delete the `/Carla` folder containing the assets before cloning the repository. Otherwise, an error will show.
[contentrepolink]: https://bitbucket.org/carla-simulator/carla-content
[gitlfslink]: https://github.com/git-lfs/git-lfs/wiki/Installation

201
Docs/build_windows.md
View File

@ -1,84 +1,113 @@
# Windows build
* [__Requirements__](#requirements):
* [__Windows build command summary__](#windows-build-command-summary)
* [__Requirements__](#requirements)
* System specifics
* [__Necessary software__](#necessary-software):
* [__Necessary software__](#necessary-software)
* Minor installations: CMake, git, make, Python3 x64
* Visual Studio 2017
* Unreal Engine 4.22
* [__CARLA build__](#carla-build):
* [__CARLA build__](#carla-build)
* Clone repository
* Get assets
* make CARLA
* make CARLA
The build process can be quite long and tedious. This documentation tries to make things clear and provides for a **[F.A.Q.](build_faq.md)** with solutions for the most common starting issues. However, the CARLA forum is open for anybody to post unexpected issues, doubts or suggestions. There is a specific section for installation issues on Windows. Feel free to login and become part of the community.
The build process can be quite long and tedious. The **[F.A.Q.](build_faq.md)** section contains the most common issues and solutions that appear during the installation. However, the CARLA forum is open for anybody to post unexpected issues, doubts or suggestions. There is a specific section for installation issues on Linux. Feel free to login and become part of the community.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>
---
## Requirements
#### System specifics
## Windows build command summary
* __x64 system:__ The simulator should run in any Windows system currently available as long as it is a 64 bits OS.
* __30GB disk space:__ Installing all the software needed and CARLA itself will require quite a lot of space, especially Unreal Engine. Make sure to have around 30/50GB of free disk space.
* __An adequate GPU:__ CARLA aims for realistic simulations, so the server needs at least a 4GB GPU. A dedicated GPU is highly recommended for machine learning.
* __Two TCP ports and good internet connection:__ 2000 and 2001 by default. Be sure neither firewall nor any other application are blocking these.
<details>
<summary> Show command lines to build on Windows</summary>
```sh
# Make sure to meet the minimum requirements.
# Necessary software:
# CMake
# Git
# Make
# Python3 x64
# Unreal Engine 4.22
# Visual Studio 2017 with Windows 8.1 SDK and x64 Visual C++ Toolset.
# Set environment variables for the software
# Clone the CARLA repository
git clone https://github.com/carla-simulator/carla
# make the CARLA server and the CARLA client
make launch
make PythonAPI
# Run an example script to test CARLA.
cd PythonAPI/Examples && python3 spawn_npc.py
```
</details>
---
## Requirements
### System specifics
* __x64 system.__ The simulator should run in any 64 bits Windows system.
* __30GB disk space.__ Installing all the software needed and CARLA will require quite a lot of space. Make sure to have around 30/50GB of free disk space.
* __An adequate GPU.__ CARLA aims for realistic simulations, so the server needs at least a 4GB GPU. A dedicated GPU is highly recommended for machine learning.
* __Two TCP ports and good internet connection.__ 2000 and 2001 by default. Be sure neither the firewall nor any other application are blocking these.
---
## Necessary software
#### Minor installations
### Minor installations
Some software is needed for the build process the installation of which is quite straightforward.
* [CMake](https://cmake.org/download/): Generates standard build files from simple configuration files.
* [Git](https://git-scm.com/downloads): Version control system to manage CARLA repositories.
* [Make](http://gnuwin32.sourceforge.net/packages/make.htm): Executable generator.
* [Python3 x64](https://www.python.org/downloads/): Main script language that CARLA provides support to. Having a x32 version installed may cause conflict even if the x64 is also there, so it is highly advisable to uninstall these.
* [__CMake__](https://cmake.org/download/) generates standard build files from simple configuration files.
* [__Git__](https://git-scm.com/downloads) is a version control system to manage CARLA repositories.
* [__Make__](http://gnuwin32.sourceforge.net/packages/make.htm) generates the executables.
* [__Python3 x64__](https://www.python.org/downloads/) is the main script language in CARLA. Having a x32 version installed may cause conflict, so it is highly advisable to have it uninstalled.
!!! Important
Be sure that these programs are added to your [environment path](https://www.java.com/en/download/help/path.xml), so you can use them from your command prompt. The path values to add lead to the _bin_ directories for each software.
Be sure that these programs are added to the [environment path](https://www.java.com/en/download/help/path.xml). Remember that the path added leads to the _bin_ directory.
#### Visual Studio 2017
### Visual Studio 2017
Get the 2017 version from [here](https://developerinsider.co/download-visual-studio-2017-web-installer-iso-community-professional-enterprise/). **Community** is the free version. Two elements will be needed to set up the environment for the build process. These must be added when using the Visual Studio Installer:
Get the 2017 version from [here](https://developerinsider.co/download-visual-studio-2017-web-installer-iso-community-professional-enterprise/). __Community__ is the free version. Use the _Visual Studio Installer_ to install two additional elements.
* **Windows 8.1 SDK**: On the right there is an _Installation details_ section. Find this SDK and select it.
* **x64 Visual C++ Toolset**: In the main _Workloads_ section, choose **Desktop development with C++**. Thus will enable a x64 command prompt that will be used for the build. After installing, check this up by pressing the `Win` button and search for `x64` (be careful to **not open a `x86_x64` prompt**). The name of this command prompt can change a bit depending on the Visual Studio installed.
* __Windows 8.1 SDK.__ Select it in the _Installation details_ section on the right.
* __x64 Visual C++ Toolset.__ In the _Workloads_ section, choose __Desktop development with C++__. This will enable a x64 command prompt that will be used for the build. Check it up by pressing the `Win` button and searching for `x64`. Be careful to __not open a `x86_x64` prompt__.
!!! Important
Having other Visual Studio versions may cause conflict during the build process, even if these have been uninstalled (Visual Studio is not that good at getting rid of itself and erasing registers). To completely clean Visual Studio from the computer run `.\InstallCleanup.exe -full` found in `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout`. This may need admin permissions.
Other Visual Studio versions may cause conflict. Even if these have been uninstalled, some registers may persist. To completely clean Visual Studio from the computer, go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`
### Unreal Engine 4.22
#### Unreal Engine 4.22
Go to [Unreal Engine](https://www.unrealengine.com/download) and download the _Epic Games Launcher_. In `Engine versions/Library`, download __Unreal Engine 4.22.x__. Make sure to run it in order to check that everything was properly installed.
Go to the [Unreal Engine](https://www.unrealengine.com/download) site and download the Epic Games Launcher. In the _Library_ section, inside the _Engine versions_ panel, download any Unreal Engine 4.22.x version. After installing it, make sure to run it in order to be sure that everything was properly installed.
!!! Note
This note will only be relevant if issues arise during the build process and manual build is required. Having VS2017 and UE4.22 installed, a **Generate Visual Studio project files** option should appear when doing right-click on **.uproject** files. If this option is not available, something went wrong while installing Unreal Engine and it may need to be reinstalled. Create a simple Unreal Engine project to check up.
!!! Note
Having VS2017 and UE4.22 installed, a __Generate Visual Studio project files__ option should appear when doing right-click on __.uproject__ files. If this is not available, something went wrong whith the UE4.22 installation. Create a UE project to check it out and reinstall if necessary.
---
## CARLA build
!!! Important
Lots of things have happened so far. It is highly advisable to do a quick restart of the system.
Lots of things have happened so far. It is highly advisable to restart the computer.
#### Clone repository
### Clone repository
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://github.com/carla-simulator/carla" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
<a href="https://github.com/carla-simulator/carla" target="_blank" class="btn btn-neutral" title="Go to the CARLA repository">
<span class="icon icon-github"></span> CARLA repository</a>
</p>
</div>
The project can be found in GitHub. It should be either downloaded and extracted or cloned on the local computer. To do so, open the **x64 terminal** previously installed and go to the path where CARLA will be installed. Then, run the following command:
The official repository of the project. Either download and extract it or clone it using the following command line in a **x64 terminal**.
```cmd
git clone https://github.com/carla-simulator/carla
@ -87,56 +116,94 @@ git clone https://github.com/carla-simulator/carla
Now the latest content for the project, known as `master` branch in the repository, has been copied in local.
!!! Note
The `master` branch contains the latest fixes and features. Stable code is inside the `stable` branch, and it can be built by changing the branch. The same goes for previous CARLA releases. Always remember to check the current branch in git with `git branch`.
The `master` branch contains the latest fixes and features. Stable code is inside the `stable` and previous CARLA versions have their own branch. Always remember to check the current branch in git with the command `git branch`.
#### Get assets
### Get assets
Only the assets package, the visual content, is yet to be downloaded. `\Util\ContentVersions.txt` contains the links to the assets for every CARLA version. These must be extracted in `Unreal\CarlaUE4\Content\Carla`. If the path doesn't exist, create it.
Download the **latest** assets to work with the current version of CARLA. When working with branches containing previous releases of CARLA, make sure to download the proper assets.
Only the assets package is yet to be downloaded. `\Util\ContentVersions.txt` contains the links to the assets for CARLA releases. These must be extracted in `Unreal\CarlaUE4\Content\Carla`. If the path doesn't exist, create it.
#### make CARLA
Download the __latest__ assets to work with the current version of CARLA.
Go to the root CARLA folder, the one cloned from the repository. It is time to do the automatic build. The process may take a while, it will download and install the necessary libraries. It might take 20-40 minutes, depending on hardware and internet connection. There are different make commands to build the different modules:
### make CARLA
Go to the root CARLA folder to make the build. The process may take a while, around 20-40 minutes, it will download and install the necessary libraries. There are different commands to build the different modules.
!!! Warning
Make sure to run __make launch__ to prepare the server and __make PythonAPI__ for the client.
Alternativelly __make libcarla__ will prepare the CARLA library to be imported anywhere.
Alternatively __make libcarla__ will prepare the CARLA library to be imported anywhere.
* **launch** will compile the server simulator and launch it in Unreal Engine. Press Play to start the spectator view and close the editor window to exit. Camera can be moved with WASD keys and rotated by clicking the scene while moving the mouse around:
```cmd
### make CARLA
The last step is to finally build CARLA. There are different `make` commands to build the different modules. All of them run in the root CARLA folder.
!!! Warning
Make sure to run __make launch__ to prepare the server and __make PythonAPI__ for the client.
Alternatively __make libcarla__ will prepare the CARLA library to be imported anywhere.
* __make launch__ compiles the server simulator and launches Unreal Engine. Press **Play** to start the spectator view and close the editor window to exit. Camera can be moved with `WASD` keys and rotated by clicking the scene while moving the mouse around.
```sh
make launch
```
The project may ask to build other instances such as `UE4Editor-Carla.dll` the first time. Agree in order to open the project. Also, during the first launch Unreal Editor may show warnings regarding shaders and mesh distance fields. These take some time to be loaded and the city will not show properly until then.
```
The project may ask to build other instances such as `UE4Editor-Carla.dll` the first time. Agree in order to open the project. During the first launch, the editor may show warnings regarding shaders and mesh distance fields. These take some time to be loaded and the city will not show properly until then.
* **PythonAPI** will compile the API client, necessary to grant control over the simulation. It is only needed the first time (remember to run it again when the CARLA code is updated). After building it, scripts can run. The following example will spawn some life into the city:
```cmd
make PythonAPI && cd PythonAPI/Examples && python3 spawn_npc.py
```
* __make PythonAPI__ compiles the API client, necessary to grant control over the simulation. It is only needed the first time. Remember to run it again when updating CARLA. Scripts will be able to run after this command is executed. The following example will spawn some life into the town.
!!! Note
If the simulation is running at very low FPS rates, open the UE4.22 editor and go to "Edit>Editor preferences>Performance" and disable: **Use less CPU when in background**.
```sh
make PythonAPI && cd PythonAPI/examples && python3 spawn_npc.py
```
!!! Important
If the simulation is running at very low FPS rates, go to `Edit/Editor preferences/Performance` in the UE editor and disable __Use less CPU when in background__.
Now everything is ready to go and CARLA has been successfully built. Here is a brief summary of the most useful `make` commands available:
Now CARLA is ready to go. Here is a brief summary of the most useful `make` commands available.
| Command | Description |
| ---------------- | --------------------- |
| `make help` | Prints all available commands. |
| `make launch` | Launches CARLA Editor. |
| `make PythonAPI` | Builds the CARLA client. |
| `make package` | Builds CARLA and creates a packaged version for distribution. |
| `make clean` | Deletes all the binaries and temporals generated by the build system. |
| `make rebuild` | make clean and make launch both in one command. |
<table class ="defTable">
<thead>
<th>Command</th>
<th>Description</th>
</thead>
<tbody>
<td>
<code>make help</code> </td>
<td>Prints all available commands.</td>
</tr>
<tr>
<td><code>make launch</code></td>
<td>Launches CARLA server in Editor window.</td>
</tr>
<tr>
<td><code>make PythonAPI</code></td>
<td>Builds the CARLA client.</td>
</tr>
<tr>
<td><code>make package</code></td>
<td>Builds CARLA and creates a packaged version for distribution.</td>
</tr>
<tr>
<td><code>make clean</code></td>
<td>Deletes all the binaries and temporals generated by the build system.</td>
</tr>
<tr>
<td><code>make rebuild</code></td>
<td>make clean and make launch both in one command.</td>
</tbody>
</table>
---
<br>
Keep reading this section to learn more about how to update CARLA, the build itself and some advanced configuration options.
Otherwise, visit the __First steps__ section to learn about CARLA:
Keep reading this section to learn how to update the build or take some first steps in CARLA.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="../core_concepts" target="_blank" class="btn btn-neutral" title="Start reading First steps">
Go to First steps</a>
<a href="../core_concepts" target="_blank" class="btn btn-neutral" title="Learn about CARLA core concepts">
Go to __First steps__</a>
</p>
<p>
<a href="../build_update" target="_blank" class="btn btn-neutral" title="Learn how to update the build">
Update CARLA</a>
</p>
</div>