docs: add advanced usage of colcon (#27)

* docs: copy documents from Autoware.Auto Create new Building page which centralizes DDS vendor info, split up troubleshooting Reorganize building & other sections Apply 1 suggestion(s) to 1 file(s) Reviewer comments Add separate DDS vendor page, mention git lfs download Move DDS info back to building, remove recommendation for Release build since autoware_compile_options does that by default Reviewer comments DDS vendor info by Esteve Touch up docs on installing/building [!821] Fix numerours code highlighting and markup issues, add TOCs - TOC still missing on design docs [!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 [!833] Add Clion configuration and more build instructions to docs Added section about colcon defaults [#912] Make code snippet blocks consistent in documentation [#813] use autoware_set_compile_options() for nearly all compiled tests - fix a few causes of warnings and disable warning flags as needed for other tests - set CXX_STANDARD strictly and only in a single place - add CMake flag `AUTOWARE_OPTIMIZATION_OF_SLOW_TARGETS`. Default: OFF - update building instructions and MR template - fix nasty initialization error of static constexpr member in `GenericState` of Kalman filter [#996] fix bashrc append in documentation export XXX=YYY >> ~/.bashrc has no effect echo "export XXX=YYY" >> ~/.bashrc is correct [#721] Add neural_networks package It provides a pool of compiled networks to the packages using them. Issue-Id: SCM-2176 Signed-off-by: Ambroise Vincent <[email protected]> Change-Id: If52ebff100eb895ef38c526bee85c40d3b8a0ca6 * update documents Signed-off-by: Kenji Miyake <[email protected]> * update documents Signed-off-by: Kenji Miyake <[email protected]> * update documents Signed-off-by: Kenji Miyake <[email protected]> * Update docs/how-to-guides/advanced-usage-of-colcon.md Co-authored-by: M. Fatih Cırıt <[email protected]> * Update docs/how-to-guides/index.md Co-authored-by: M. Fatih Cırıt <[email protected]> * Update docs/how-to-guides/index.md Co-authored-by: M. Fatih Cırıt <[email protected]> Co-authored-by: Nikolai Morin <[email protected]> Co-authored-by: Keisuke Shima <[email protected]> Co-authored-by: M. Fatih Cırıt <[email protected]>
autowarefoundation · Mar 11, 2022 · 1a176e4 · 1a176e4
1 parent d631be2
commit 1a176e4
Show file tree

Hide file tree

Showing 3 changed files with 131 additions and 4 deletions.
diff --git a/docs/how-to-guides/.pages b/docs/how-to-guides/.pages
@@ -1,2 +1,3 @@
 nav:
   - index.md
+  - advanced-usage-of-colcon.md
diff --git a/docs/how-to-guides/advanced-usage-of-colcon.md b/docs/how-to-guides/advanced-usage-of-colcon.md
@@ -0,0 +1,126 @@
+# Advanced usage of colcon
+
+This page shows some advanced and useful usage of `colcon`.
+If you need more detailed information, refer to the [colcon documentation](https://colcon.readthedocs.io/).
+
+## Common mistakes
+
+### Do not run from other than the workspace root
+
+It is important that you always run `colcon build` from the workspace root because `colcon` builds only under the current directory.
+If you have mistakenly built in a wrong directory, run `rm -rf build/ install/ log/` to clean the generated files.
+
+### Do not unnecessarily overlay workspaces
+
+`colcon` overlays workspaces if you have sourced the `setup.bash` of other workspaces before building a workspace.
+You should take care of this especially when you have multiple workspaces.
+
+Run `echo $COLCON_PREFIX_PATH` to check whether workspaces are overlaid.
+If you find some workspaces are unnecessarily overlaid, remove all built files, restart the terminal to clean environment variables, and re-build the workspace.
+
+For more details about `workspace overlaying`, refer to the [ROS2 documentation](https://docs.ros.org/en/rolling/Tutorials/Workspace/Creating-A-Workspace.html#source-the-overlay).
+
+## Cleaning up the build artifacts
+
+`colcon` sometimes causes errors of because of the old cache.
+To remove the cache and rebuild the workspace, run the following command:
+
+```bash
+rm -rf build/ install/
+```
+
+In case you know what packages to remove:
+
+```bash
+rm -rf {build,install}/{package_a,package_b}
+```
+
+## Selecting packages to build
+
+To just build specified packages:
+
+```bash
+colcon build --packages-select <package_name1> <package_name2> ...
+```
+
+To build specified packages and their dependencies recursively:
+
+```bash
+colcon build --packages-up-to <package_name1> <package_name2> ...
+```
+
+You can also use these options for `colcon test`.
+
+## Changing the optimization level
+
+Set `DCMAKE_BUILD_TYPE` to change the optimization level.
+
+!!! warning
+
+    If you specify `DCMAKE_BUILD_TYPE=Debug` or no `DCMAKE_BUILD_TYPE` is given for building the entire Autoware, it may be too slow to use.
+
+```bash
+colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug
+```
+
+```bash
+colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
+```
+
+```bash
+colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
+```
+
+## Changing the default configuration of colcon
+
+Create `$COLCON_HOME/defaults.yaml` to change the default configuration.
+
+```bash
+mkdir -p ~/.colcon
+cat << EOS > ~/.colcon/defaults.yaml
+{
+    "build": {
+        "symlink-install": true
+    }
+}
+```
+
+See [here](https://colcon.readthedocs.io/en/released/user/configuration.html#defaults-yaml) for more details.
+
+## Generating compile_commands.json
+
+[compile_commands.json](https://colcon.readthedocs.io/en/released/user/how-to.html#cmake-packages-generating-compile-commands-json) is used by IDEs/tools to analyze the build dependencies and symbol relationships.
+
+You can generate it with the flag `DCMAKE_EXPORT_COMPILE_COMMANDS=1`:
+
+```bash
+colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1
+```
+
+## Seeing compiler commands
+
+To see the compiler and linker invocations for a package, use `VERBOSE=1` and `--event-handlers console_cohesion+`:
+
+```bash
+VERBOSE=1 colcon build --packages-up-to <package_name> --event-handlers console_cohesion+
+```
+
+See [here](https://colcon.readthedocs.io/en/released/reference/event-handler-arguments.html) for other options.
+
+## Using Ccache
+
+[Ccache](https://ccache.dev/) can speed up recompilation.
+It is recommended to use it to save your time unless you have a specific reason not to do so.
+
+1. Install `Ccache`:
+
+   ```bash
+   sudo apt update && sudo apt install ccache
+   ```
+
+2. Write the following in your `.bashrc`:
+
+   ```bash
+   export CC="/usr/lib/ccache/gcc"
+   export CXX="/usr/lib/ccache/g++"
+   ```
diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md
@@ -1,11 +1,11 @@
 # How-to guides
 
-!!! warning
+- [Advanced usage of colcon](advanced-usage-of-colcon)
 
-    Under Construction
+TODO: Write the following contents.
 
-- Write an Autoware package
-- Add a message
+- Create an Autoware package
+- Add a custom ROS message
 - Debug Autoware
 - Integrate Autoware with a real vehicle
 - etc.