1. If at this point, you do not have a vehicle setup or you want to confirm that Apollo has been built out correctly, please continue to [How to Launch and Run Apollo](how_to_launch_Apollo.md)
2. If you do have a vehicle setup, please continue back to our [Software Installation guide](https://github.com/ApolloAuto/apollo/blob/master/docs/quickstart/apollo_software_installation_guide.md)
## Build in Visual Studio Code
### Install VSCode
The easiest way to install for Debian/Ubuntu based distributions is to download from https://code.visualstudio.com and install the .deb package (64-bit) either through the graphical software center if it's available or through the command line with:
```bash
sudo dpkg -i <file>.deb
sudo apt-get install-f# Install dependencies
```
### Start VSCode
Start VSCode with the following command:
```bash
code
```
### Open the Apollo project in VSCode
Use the keyboard shortcut **(Ctrl+K Ctrl+O)** to open the Apollo project.
### Build the Apollo project in VSCode
Use the keyboard shortcut **(Ctrl+Shift+B)** to build the Apollo project.
### Run all unit tests for the Apollo project in VSCode
Select the "Tasks->Run Tasks..." menu command and click "run all unit tests for the apollo project" from a popup menu to check the code style for the Apollo project.
If you are currently developing on 16.04, you will get a build error.
As seen in the image below, 2 perception tests. To avoid this build error, refer to the [how to build Apollo using Ubuntu 16](how_to_run_apollo_2.5_with_ubuntu16.md).
### Run a code style check task for the Apollo project in VSCode
Select the "Tasks->Run Tasks..." menu command and click "code style check for the apollo project" from a popup menu to check the code style for the Apollo project.
### Clean the Apollo project in VSCode
Select the "Tasks->Run Tasks..." menu command and click "clean the apollo project" from a popup menu to clean the Apollo project.
### Change the building option
You can change the "build" option to another one such as "build_gpu" (refer to the "apollo.sh" file for details) in ".vscode/tasks.json"
The *HMI* will automatically start and you can control each apollo module through any web browser by inputting IP address and port number, such as *localhost:8887*. You can get into the release container if quick fix needed.
```bash
bash docker/scripts/release_into.sh
```
## Legal Disclaimer
The docker image that you build may contain ESD CAN library files provided by ESD Electronics (hereby referred as ESD), which you should have obtained via a licensing agreement with ESD. The licensing agreement shall have granted you (as an individual or a business entity) the right to use the said software provided by ESD; however, you may (and likely you do) need explicit re-distribution permission from ESD to publish the docker image for any other third party to consume. Such licensing agreement is solely between you and ESD, and is not covered by the license terms of the Apollo project (see file LICENSE under Apollo top directory).
The Apollo project runs in Docker and cannot be used directly on the host machine. It must be created in Docker with GDBServer. Debug the service process, and then use GDB to connect to the debug service process in Docker on the host machine. The specific operation methods are as follows:
### Prerequisites
The main prerequisites contain collecting debugging information and installing the GDBServer if it is not already present in Docker
#### Collecting debugging information
When compiling Apollo projects, you will need to use debugging information options **build_dbg**. Optimization options such as **build_opt** or **build_opt_gpu** cannot be used.
#### Install GDBServer inside Docker
After entering Docker, you can use the following command to view if the GDBServer is present:
``` bash
gdbserver --version
```
If the prompt is similar to the following information:
```
GNU gdbserver (Ubuntu 8.1-0ubuntu3.2) 8.1.0.20180409-git
Copyright (C) 2018 Free Software Foundation, Inc.
gdbserver is free software, covered by the GNU General Public License.
This gdbserver was configured as "x86_64-linux-gnu"
```
It means that GDBServer has been installed inside Docker. You should be able to view the prompt below. But if the GDBServer is not present and if you are prompted with the following information:
```
bash: gdbserver: command not found
```
Then you would need to install the GDBServer using
```bash
sudo apt-get -y update
sudo apt-get install gdbserver
```
#### Start the Dreamview daemon
Go to Docker and start Dreamview. The command is as follows:
```
cd ${APOLLO_ROOT_DIR}
# If Docker is not started, start it first, otherwise ignore this step
bash docker/scripts/dev_start.sh -C
# Enter Docker
bash docker/scripts/dev_into.sh
# Start Dreamview background service
bash scripts/bootstrap.sh
```
#### Start the module that needs debugging
Start the module to be debugged, either by using the command line or by using the Dreamview interface. The following is an example of debugging the **Planning** module from the Dreamview interface. Open Chrome browser, enter the URL: http://localhost:8888/, open the Dreamview interface, open the **SimControl** option, as shown below:
Click on the `Module Controler` tab on the left toolbar and select the `Routing` and `Planning` options as shown below:
Click the `Default Routing` tab on the left toolbar, select `Route: Reverse Early Change Lane` or any of these options, send a `Routing Request` request, and generate a global navigation path, as shown below:
Use the following command to view the "Planning" process ID:
``` bash
ps aux | grep mainboard | grep planning
```
The result in the following figure is similar to the previous figure, you can see that the `Planning` process ID is 4147.
#### Debugging Planning module using GDBServer
Next we need to carry out our key operations, using GDBServer to additionally debug the `Planning` process, the command is as follows:
``` bash
sudo gdbserver :1111 --attach 4147
```
In the above command, ":1111" indicates that the debugging service process with the port "1111" is enabled, and "4147" indicates the "Planning" process ID. If the result is as shown below, the operation is successful.
After restarting a command terminal and entering Docker, use the following command to see that the "gdbserver" process is running normally:
``` bash
ps aux | grep gdbserver
```
#### Starting GDBServer with a Script File
`docker/scripts/dev_start_gdb_server.sh` which starts GDBServer directly on the host (outside Docker).
Assuming that while debugging the planning module, the port number is 1111, the usage of `docker/scripts/dev_start_gdb_server.sh` is:
``` bash
# Start gdbserver directly on the host machine (outside Docker)
During the debugging process, you may encounter the following problems:
#### the network connection is not smooth, can not be debugged
#### Solution
The solution is to ensure the network is smooth, and disable the agent tool
### Remote debugging
During the R&D process, we also need to remotely debug the Apollo project on the industrial computer inside the vehicle, that is, connect the in-vehicle industrial computer with the SSH service on the debugging computer, start the relevant process in the industrial computer, and then perform remote debugging on the debugging computer. The following is an example of debugging the planning module:
#### View the IP address of the industrial computer in the car
On the industrial computer in the car, check the IP of the machine by the following command:
``` bash
ifconfig
```
#### Open Dreamview in the browser of the debugging computer and start the module to be debugged
Assuming that the IP address of the industrial computer LAN is: 192.168.3.137, open your Chrome or Firefox browser, enter the following URL: http://192.168.3.137:8888/, start the module (`Planning`) to be debugged as shown in [Start the module that needs debugging](#Start-the-module-that-needs-debugging) section
#### Use the SSH Command to Remotely Log In to the Industrial PC and Start the Gdbserver Service of the Industrial PC
Assume that the user name of the industrial computer in the car is `xxxxx`, and the IP address of the LAN is `192.168.3.137`. Use the following command to remotely log in to the industrial computer:
```bash
ssh xxxxx@192.168.3.137
```
After successfully entering the IPC, assume that the Planning module needs to be debugged, and the port number is 1111, use the following command to start the gdbserver service of the in-vehicle IPC:
``` bash
# Switch to the Apollo project root directory on the industrial computer
