From 0955ffef65c1935b25028d84b512654a2ea67d66 Mon Sep 17 00:00:00 2001 From: Joel Spadin Date: Sat, 19 Sep 2020 16:32:24 -0500 Subject: [PATCH] docs: Add docs for setting up vscode Added a docs page with tips for setting up VS Code's code completion to work in ZMK's source files. Info for other IDEs can be added here later as needed. --- docs/docs/development/ide-integration.md | 139 +++++++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 140 insertions(+) create mode 100644 docs/docs/development/ide-integration.md diff --git a/docs/docs/development/ide-integration.md b/docs/docs/development/ide-integration.md new file mode 100644 index 00000000..20ab6926 --- /dev/null +++ b/docs/docs/development/ide-integration.md @@ -0,0 +1,139 @@ +--- +title: IDE Integration +sidebar_label: IDE Integration +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +## Visual Studio Code + +Visual Studio Code needs to know some things about the project such as include +paths and compiler paths before features such as code completion, go to definition, +and graying out disabled code blocks will work. Fortunately, CMake can generate +that configuration for us automatically. + +### Create a Compilation Database + +To configure `west` to tell CMake to generate a compilation database, open a +terminal to the ZMK repository and run the following command: + +```sh +west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +``` + +Every [build](build-flash#building) will now update the database. You will +need to build once to create the database before code completion will work. +We'll tell Visual Studio Code where to find the database in the next step. + +:::note +If you have set any other CMake arguments such as the path to your zmk-config, the +above command will overwrite them. You should instead provide the flag to export +compile commands and all other arguments surrounded by quotes. For example: + +```sh +west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DZMK_CONFIG=/path/to/zmk-config/config" +``` + +::: + +### Create a C/C++ Configuration + +Install the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools), +then run **F1 > C/C++: Edit Configurations (UI)**. It should automatically create +a new configuration for you, but if the text box under **Configuration name** is empty, +click **Add Configuration**, enter a name, and click **OK**. + +Change these options: + +| Option | Value | +| ------------------------------------- | ---------------------------------------------------- | +| Compiler path | Path to your toolchain's GCC binary (see below) | +| IntelliSense mode | gcc-arm | +| Advanced Settings > Compiler commands | `${workspaceFolder}/app/build/compile_commands.json` | + + + + +Open VS Code's integrated terminal and run the following commands. It will print +your compiler path. + +```sh +source zephyr/zephyr-env.sh +echo ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc +``` + +:::note +You will need to update this path any time you switch to a new version of the Zephyr SDK. +::: + + + + +Your compiler path is + +``` +${env:GNUARMEMB_TOOLCHAIN_PATH}/bin/arm-none-eabi-gcc.exe +``` + +This assumes `GNUARMEMB_TOOLCHAIN_PATH` is set in your system or user environment variables. +If not, you will need to list the full path instead of using the `${env}` placeholder. + + + + +Open VS Code's integrated terminal and run the following command. It will print +your compiler path. + +```sh +echo ${GNUARMEMB_TOOLCHAIN_PATH}/bin/arm-none-eabi-gcc +``` + + + + +Your compiler path is + +``` +/usr/bin/arm-none-eabi-gcc +``` + + + + +Open VS Code's integrated terminal and run the following commands. It will print +your compiler path. + +```sh +source zephyr/zephyr-env.sh +echo ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc +``` + +:::note +You will need to update this path any time you switch to a new version of the Zephyr SDK. +::: + + + + +Your compiler path is + +``` +${env:ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc +``` + + + diff --git a/docs/sidebars.js b/docs/sidebars.js index 98ffb19e..e98b3f81 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -49,6 +49,7 @@ module.exports = { "development/posix-board", "development/tests", "development/usb-logging", + "development/ide-integration", { type: "category", label: "Guides",