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
@@ -81,4 +82,5 @@ repos:
         args: [--fix]
         stages: [pre-commit]
 
+exclude: irnas.code-profile
 default_install_hook_types: [pre-commit, commit-msg]

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,103 @@
-# 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
+
+Currently supported operating systems:
+
+- Linux (specifically Ubuntu)
+- MacOS
+
+## Editor and extra tooling
+
+1. To install VsCode run:
+
+   ```shell
+   ./installation_scripts/install_vscode.sh
+   ```
+
+2. To install LLVM tools run (make sure that all instances of VSCode are closed at this point):
+
+   ```shell
+   ./installation_scripts/install_llvm.sh
+   ```
+
+## Installing configuration
+
+You can setup configuration in two ways.
+
+### Importing Profile file
+
+1. Open VSCode.
+2. Select _cogwheel_ icon on the bottom-left.
+3. Navigate through _Profiles -> Import Profile -> Select File_ and select `irnas.code-profile` file
+   in this repo.
+4. Click _Create Profile_ button on the bottom-left.
+5. Choose a name for the profile and then click _Create_ button.
+
+The configuration and extensions will be applied to the VSCode editor.
+
+### Symlinks
+
+To install extensions and symlink VSCode settings to its correct location run:
+
+```shell
+./installation_scripts/install_extensions.sh
+cd dotfiles
+./place_dotfiles.sh
+```
+
+## Maintaining your configuration and expected workflow
+
+### Using Profiles
+
+Users can maintain two Profiles inside the VSCode:
+
+- `irnas` - This should be the one provided by this repo.
+- and custom user Profile, built on top of the `irnas` one.
+
+Whenever this repository is updated users can update the `user` Profile and then bring desired
+changes to their custom Profile.
+
+### Using symlinks
+
+`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
+repository 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.
+
+## 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`

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

@@ -0,0 +1,78 @@
+{
+  // General settings
+  "editor.formatOnSave": true,
+  "files.associations": {
+    "CMakeLists.txt": "cmake",
+    "*.h": "c",
+    "*.hpp": "c",
+    "*.cpp": "c",
+    "*defconfig": "kconfig",
+    "*.conf": "kconfig"
+  },
+  "files.trimTrailingWhitespace": true,
+  "files.trimFinalNewlines": true,
+  "files.insertFinalNewline": true,
+  "[c][cpp]": {
+    "editor.detectIndentation": false,
+    "editor.tabSize": 8,
+    "editor.insertSpaces": false,
+    "editor.rulers": [
+      100
+    ],
+    "editor.defaultFormatter": "xaver.clang-format"
+  },
+  // Don't change focus, when debugging.
+  "debug.focusWindowOnBreak": false,
+  "debug.focusEditorOnBreak": false,
+  "[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,
+  // Does not ask with popup when you want to delete files
+  "explorer.confirmDelete": false,
+  "diffEditor.ignoreTrimWhitespace": false,
+  // Extensions
+  "clang-format.executable": "/usr/bin/clang-format-18",
+  "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",
+  "github.copilot.enable": {
+    // Enable for everything, except plain text and git input boxes.
+    "*": true,
+    "plaintext": false,
+    "scminput": false
+  },
+}

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}"
+        rm ${dest}
+
+    elif [ -f "${dest}" ]; then
+        # Existing file
+        echo "Backing up existing file: ${dest}"
+        mv ${dest}{,.${dateStr}}
+
+    elif [ -d "${dest}" ]; then
+        # Existing dir
+        echo "Backing up existing dir: ${dest}"
+        mv ${dest}{,.${dateStr}}
+    fi
+
+    echo "Creating new symlink: ${dest}"
+    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