feat: add VSCode config files and docs

.pre-commit-config.yaml

@@ -59,6 +59,7 @@ repos:
     rev: v0.10.0.1
     hooks:
       - id: shellcheck
+        args: [--exclude=SC2086]
         stages: [pre-commit]
   - repo: https://github.com/lovesegfault/beautysh
     rev: v6.2.1

CHANGELOG.md

@@ -5,3 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
+
+### Added
+
+-   Initial project structure and VSCode configs.

README.md

@@ -1,18 +1,71 @@
-# Irnas's Projects template
-
-IRNAS template for a GitHub repository. It comes with a
-[basic group](https://github.com/IRNAS/irnas-workflows-software/tree/main/workflow-templates/basic)
-of CI workflows for release automation.
-
-## Checklist
-
-- [ ] Provide a concise and accurate description of your project in the GitHub
-      "description" field.
-- [ ] Provide a concise and accurate description of your project in this
-      `README.md` file, replace the title.
-- [ ] Ensure that your project follows
-      [repository naming scheme](https://github.com/IRNAS/irnas-guidelines-docs/blob/main/docs/github_projects_guidelines.md#repository-naming-scheme-).
-- [ ] Turn on `gitlint` tool by running `gitlint install-hook`. If you do not
-      have it yet, follow instructions
-      [here](https://github.com/IRNAS/irnas-guidelines-docs/tree/main/tools/gitlint).
-- [ ] As the final step delete this checklist and commit changes.
+# VSCode setup by IRNAS
+
+![vscode-banner](images/vscode-banner.webp)
+
+## Introduction
+
+This repository contains installation scripts and configuration files for setting up the VSCode
+editor from scratch. The configuration files inside the `dotfiles/.config/Code` are pretty
+opinionated. They are suitable for embedded Zephyr/NCS development, writing Python scripts and
+JavaScript/React Native applications.
+
+The configuration is especially coupled to our `.pre-commit-config.yaml` file in the
+[irnas-zephyr-template] repo, as it sets up formatters, linters and other tools that are used by the
+`pre-commit` tool.
+
+[irnas-zephyr-template]: https://github.com/IRNAS/irnas-zephyr-template/tree/main
+
+## Setup
+
+1. To install VsCode run:
+
+   ```shell
+   ./installation_scripts/install_vscode.sh
+   ```
+
+2. To install all extensions run:
+
+   ```shell
+   ./installation_scripts/install_extensions.sh
+   ```
+
+3. To symlink VSCode settings to its correct location:
+
+   ```shell
+   cd dotfiles
+   ./place_dotfiles.sh
+   ```
+
+4. Open VSCode. All extensions are now installed, all that is left to do is to configure some
+   specific paths, follow instructions in the pop-up notifications.
+
+## Backing up existing settings
+
+If you care about your current VSCode configuration you may want to backup below folders:
+
+On Windows:
+
+- `%APPDATA%\Code`
+- `%USERPROFILE%\.vscode`
+
+On Linux and macOS:
+
+- `$HOME/.config/Code/`
+- `$HOME/.vscode`
+
+### Maintaining your configuration and expected workflow
+
+`place_dotfiles.sh` creates a symlink for the `.config/Code` alongside it to its correct location in
+the `~/` home directory.
+
+This means that whatever changes are made in the `~/.config/Code`, they are reflected in this repo
+and thus visible in the `git` version control system.
+
+Developers can thus:
+
+- fork this repo to their personal GitHub account,
+- start with a good working VSCode configuration,
+- expand it further by their preferences, commit changes and
+- sync with the upstream repo, when they want to fetch new commits.
+
+Developers can also manually copy the things that they want and manually update when they want to.

dotfiles/.config/Code/User/settings.json

@@ -0,0 +1,65 @@
+{
+  // General settings
+  "editor.formatOnSave": true,
+  "files.associations": {
+    "CMakeLists.txt": "cmake",
+    "*.h": "c"
+  },
+  "files.trimTrailingWhitespace": true,
+  "files.trimFinalNewlines": true,
+  "files.insertFinalNewline": true,
+  "[c][cpp]": {
+    "editor.detectIndentation": false,
+    "editor.tabSize": 8,
+    "editor.insertSpaces": false
+  },
+  // Don't change focus, when debugging.
+  "debug.focusWindowOnBreak": false,
+  "debug.focusEditorOnBreak": false,
+  "[c]": {
+    "editor.defaultFormatter": "xaver.clang-format"
+  },
+  "editor.cursorBlinking": "smooth",
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "editor.autoClosingComments": "always",
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "git.openRepositoryInParentFolders": "never",
+  "security.workspace.trust.enabled": false,
+  // Extensions
+  "clang-format.executable": "/usr/bin/clang-format-17",
+  "errorLens.enabledDiagnosticLevels": [
+    "error",
+    "warning",
+    "info",
+    "hint"
+  ],
+  "auto-comment-blocks.singleLineBlockOnEnter": true,
+  "errorLens.messageEnabled": false,
+  "errorLens.gutterIconsEnabled": true,
+  "doxdocgen.generic.paramTemplate": "@param[in] {param} ",
+  "doxdocgen.generic.returnTemplate": "@return ",
+  "clangd.arguments": [
+    "--enable-config",
+    "--query-driver=/usr/bin/**/clang-*,/bin/clang,/bin/clang++,/usr/bin/gcc,/usr/bin/g++,${env:HOME}/gnuarmemb/bin/arm-none-eabi-gcc",
+    "--all-scopes-completion",
+    "--background-index",
+    "-j=8",
+    "--clang-tidy",
+    "--completion-style=detailed",
+    "--function-arg-placeholders",
+    "--header-insertion-decorators",
+    "--header-insertion=never",
+    "--pch-storage=memory"
+  ],
+  "cortex-debug.enableTelemetry": false,
+  "cortex-debug.liveWatchRefreshRate": 250,
+  "C_Cpp.intelliSenseEngine": "disabled",
+  "workbench.colorTheme": "Default Dark Modern",
+}

dotfiles/.config/Code/User/snippets/c.json

@@ -0,0 +1,72 @@
+{
+  "hfile": {
+    "prefix": [
+      "hfile"
+    ],
+    "body": [
+      "/** @file $TM_FILENAME_BASE.h",
+      " *",
+      " * @brief ${2:A description of the module's purpose.}",
+      " *",
+      " * @par",
+      " * COPYRIGHT NOTICE: (c) $CURRENT_YEAR Irnas. All rights reserved.",
+      " */",
+      "",
+      "#ifndef ${TM_FILENAME_BASE/(.*)/${1:/upcase}/}_H",
+      "#define ${TM_FILENAME_BASE/(.*)/${1:/upcase}/}_H",
+      "",
+      "#ifdef __cplusplus",
+      "extern \"C\" {",
+      "#endif",
+      "",
+      "${0}",
+      "",
+      "#ifdef __cplusplus",
+      "}",
+      "#endif",
+      "",
+      "#endif /* ${TM_FILENAME_BASE/(.*)/${1:/upcase}/}_H */",
+      "",
+    ],
+    "description": "IRNAS .h file template"
+  },
+  "cfile": {
+    "prefix": [
+      "cfile"
+    ],
+    "body": [
+      "/** @file $TM_FILENAME_BASE.c",
+      " * ",
+      " * @par       ",
+      " * COPYRIGHT NOTICE: (c) $CURRENT_YEAR Irnas. All rights reserved.",
+      " */",
+      "",
+      "",
+      "#include \"$TM_FILENAME_BASE.h\"",
+      "",
+      "${0}",
+      "",
+    ],
+    "description": "IRNAS .c file template"
+  },
+  "slc": {
+    "prefix": [
+      "slc"
+    ],
+    "body": [
+      "/* ${0} */"
+    ],
+    "description": "C89-style single line comment"
+  },
+  "mlc": {
+    "prefix": [
+      "mlc"
+    ],
+    "body": [
+      "/*",
+      " * ${0}",
+      " */"
+    ],
+    "description": "C89-style multi line comment"
+  }
+}

dotfiles/place_dotfiles.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+dotfilesDir=$(pwd)
+
+function linkDotfile {
+    dest="${1}/${2}"
+    dateStr=$(date +%Y-%m-%d-%H%M)
+
+    if [ -h ~/${2} ]; then
+        # Existing symlink
+        echo "Removing existing symlink: ${dest}"
+        sudo rm ${dest}
+
+    elif [ -f "${dest}" ]; then
+        # Existing file
+        echo "Backing up existing file: ${dest}"
+        sudo mv ${dest}{,.${dateStr}}
+
+    elif [ -d "${dest}" ]; then
+        # Existing dir
+        echo "Backing up existing dir: ${dest}"
+        sudo mv ${dest}{,.${dateStr}}
+    fi
+
+    echo "Creating new symlink: ${dest}"
+    sudo ln -s ${dotfilesDir}/${2} ${dest}
+}
+
+# Create config folder if it does not exists, below symlinks fail otherwise
+mkdir -p ~/.config
+
+# Create symlink for a file/folder on a right in the folder on the left
+linkDotfile /home/"$USER" .config/Code

installation_scripts/install_extensions.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+function install {
+    code --install-extension "$1"
+}
+
+# General development core
+install eamodio.gitlens
+install usernamehw.errorlens
+
+# C/C++ extensions
+install xaver.clang-format
+install cheshirekow.cmake-format
+install twxs.cmake
+install llvm-vs-code-extensions.vscode-clangd
+install cschlosser.doxdocgen
+install IRNAS.auto-comment-blocks-single-star
+install harry-ross-software.c-snippets
+install jeff-hykin.better-c-syntax
+install jeff-hykin.better-cpp-syntax
+
+# JS/TS extensions
+install esbenp.prettier-vscode # Also used for formatting markdown files.
+install dbaeumer.vscode-eslint
+install xabikos.JavaScriptSnippets
+
+# Python extensions
+install ms-python.python
+install magicstack.MagicPython
+install charliermarsh.ruff
+install njpwerner.autodocstring
+install frhtylcn.pythonsnippets
+
+# Cmake
+install twxs.cmake
+install cheshirekow.cmake-format
+
+# Docker
+install ms-azuretools.vscode-docker
+install exiasr.hadolint
+
+# Jupyter
+install ms-toolsai.jupyter
+
+# Embedded development
+install marus25.cortex-debug
+install ms-vscode.vscode-embedded-tools
+install keroc.hex-fmt
+
+# Extras
+install ms-vscode-remote.vscode-remote-extensionpack
+install tekumara.typos-vscode
+install DavidAnson.vscode-markdownlint
+install yzhang.markdown-all-in-one
+install github.copilot
+install github.copilot-chat
+install Graphite.gti-vscode
+install wayou.vscode-todo-highlight
+install mattlott.copy-github-url
+install redhat.vscode-yaml
+install tamasfe.even-better-toml
+install coolchyni.beyond-debug
+install vsciot-vscode.vscode-arduino
+
+# Themes
+install github.github-vscode-theme
+install liviuschera.noctis
+install anoff.theme-monokai-light
+
+# Extra tools needed by some extensions, but not directly provided by them.
+pip install cmake-format

installation_scripts/install_vscode.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# Add microsoft's repository to apt
+sudo apt update
+sudo apt install software-properties-common apt-transport-https wget
+wget -q https://packages.microsoft.com/keys/microsoft.asc -O- | sudo apt-key add -
+sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main"
+
+# install
+sudo apt install code