Getting started

Getting started

Welcome to sparq!

We intended sparq to be a vcpkg package and this guide will help you integrate the sparq embedded framework into your application using vcpkg Manifest Mode and CMake paired with CMake Presets

This setup allows IDEs (like VS Code, CLion or Visual Studio) to automatically configure, fetch and compile all dependencies in the background

Prerequisites

• CMake (v3.21 or higher for full workflow preset support)
• vcpkg (Installed and accessible on your system)
• created an environment variable VCPKG_ROOT set to your vcpkg installation path
• git (To access the base42-vcpkg-registry)

Quick start integration

Follow these four steps to connect to our private registry(base42-vcpkg-registry) and add sparq to your project

1. Configure the registry

Create a file named vcpkg-configuration.json in your aplication's root directory. This tells vcpkg to fetch the sparq package from base42-vcpkg-registry instead of the public index

{
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/42dotmk/base42-vcpkg-registry",
      "baseline": "get-hash-from-last-commit-of-main-branch",
      "packages": [ 
        "sparq" 
      ]
    }
  ]
}

2. Declare the dependency

Create a vcpkg.json file in your application's root directory to declare your dependency on the framework

{
  "name": "your-application-name",
  "version": "1.0.0",
  "dependencies": [
    "sparq"
  ]
}

3. Create the CMake Presets Instead of typing out long toolchain paths manually, create a CMakePresets.json file in your root directory. This file points directly to the vcpkg toolchain using your VCPKG_ROOT environment variable

{
  "version": 3,
  "configurePresets": [
    {
      "name": "default-vcpkg",
      "displayName": "Default with vcpkg",
      "description": "Standard configuration using vcpkg toolchain",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": {
          "type": "FILEPATH",
          "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
        }
      }
    }
  ]
}

4. Wire up your CMakeLists.txt

Add the standard CMake commands to find and link the sparq library to your executable

cmake_minimum_required(VERSION 3.23)
project(YourEmbeddedApp VERSION 0.0.1 LANGUAGES CXX)

# Find the sparq package provided by vcpkg
find_package(sparq REQUIRED)

add_executable(YourEmbeddedApp src/main.cpp)

# Link sparq to your application target
target_link_libraries(YourEmbeddedApp PRIVATE sparq::sparq)

IDE Integration & Building

You do not need to use the command line or run manual installations. IDEs read your CMakePresets.json automatically

Using CMake GUI and Visual Studio IDE (recommended)

1. Open the CMake GUI application
2. In "Where is the source code", browse to your project's root directory
3. CMake GUI will instantly detect your presets. Look for the Preset: dropdown menu at the top
4. Select your preset(default-vcpkg for us) from the dropdown menu
5. Click the Generate button, this will automatically call Configure first, vcpkg will run in the background to fetch and prepare sparq and then create the Visual Studio solution files
6. Click the Open Project button right next to it. This launches Visual Studio with your newly generated solution ready to go

Using VS Code

1. Install the CMake Tools and C/C++ extensions
2. Open your project folder
3. Select your named preset("Default with vcpkg" in our case) from the CMake Presets list in the status bar(or via the command palette)
4. Click Configure or Build. VS Code will trigger vcpkg to pull sparq down and compile it seamlessly

Using CLion

1. Open your project folder. CLion will detect CMakePresets.json immediately
2. Go to Settings > Build, Execution, Deployment > CMake
3. Enable your preset("Default with vcpkg" in our case) profile
4. Click the Build hammer icon

Template for future expansion

Whenever there will be vcpkg features for specific hardware support, this template will serve as a blueprint on how to update the current obscure version of vcpkg.json:

{
    "name": "sparq",
    "version": "0.0.1",
    "description": "base42's embedded framework",
    "dependencies": [
        {
            "name": "",
            "features": [
                ""
            ],
            "version>=": ""
        }
    ],
    "features": {
        "test": {
            "description": "test utilities",
            "dependencies": [
                "gtest"
            ]
        },
        "": {
            "description": "support for ... devices",
            "dependencies": [
                {
                    "name": "",
                    "features": [
                        ""
                    ]
                }
            ]
        }
    }
}