Skip to content

Latest commit

 

History

History
297 lines (213 loc) · 12.8 KB

README.md

File metadata and controls

297 lines (213 loc) · 12.8 KB

c++temp-toplogo

MarkWare VCMake

Ubuntu MacOS Windows

Overview

MarkWare VCMake is a comprehensive, modern C++ project template designed for cross-platform development in Visual Studio Code. The template provides a robust foundation for both standalone executables and libraries, incorporating industry best practices and modern build tools.

With automatic installers you are just seconds away from starting 🚀 development. 💻✨

Key Features🎈

  • Modern projects design Standalone & Library
  • The template is universal for Linux, MacOS, Windows
  • Modern CMake with targets object design
  • Integrated Conan 2 with declaration in conanfile.py
  • Target linking with CPM.cmake, CPM.license
  • Extended argument parsing with cxxopt (cxxoptwiki)
  • Sanitizers, Static Analysis, and Hardening
  • Created with an emphasis on Cross-compilation capabilities
  • Automated Wrapper for CMake Build System by VSCode Tasks
  • Native C++ debugging by Microsoft C++ extension
  • CMake debugger
  • GitHub Actions workflows for continuous integration
  • Template Renamer
  • Template Upgrader
  • Compatible with SSH, WSL remote development

Some of My Older Projects Using MarkWare VCMake

MWImGuiStarter, MWwxWidgetsStarter, MyPersonalDiscordBot, snake-in-shell-cpp, MassCode2Md

Getting Started

Important Decision!
For MarkWare VCMake to function properly, you need to have the software installed that is used either directly by the project configuration itself or by the workflow that occurs in VSCode when working with MarkWare VCMake. You have two options. You can manually add dependencies one by one, which might be the more complex but better option for already used systems, or you can use automatic installation scripts, which are most suitable for a freshly installed system, as the scripts will install everything from scratch to a functional solution.

Manual Installation

As a developer, you will most likely already have most of the tools listed below installed on your system.

Tools

Compilers

Crosstools

Automatic installation for fresh systems

Debian

curl -sSL https://raw.githubusercontent.com/tomasmark79/MarkWareVCMake/main/.init/installers/DebianBasedInstaller.sh | bash

Fedora

curl -sSL https://raw.githubusercontent.com/tomasmark79/MarkWareVCMake/main/.init/installers/FedoraInstaller.sh | bash

Windows

powershell -Command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/tomasmark79/MarkWareVCMake/main/.init/installers/WindowsInstaller.ps1' -OutFile 'WindowsInstaller.ps1'; Set-ExecutionPolicy Bypass -Scope Process -Force; .\WindowsInstaller.ps1"

Note for Windows Users: The CMake generator argument -G "MinGW Makefiles" is hardcoded in the SolutionController.py script at line 227. If you prefer to use a different CMake generator, please modify this line accordingly.

Cloning the Repository

To clone the MarkWare VCMake repository, execute the following command:

git clone https://github.com/tomasmark79/MarkWareVCMake ./

Launching Visual Studio Code

To start Visual Studio Code from the root directory of MarkWare VCMake, use the following command:

code .

Development Workflow

One of the first things you should do when you open VSCode is to install the necessary extensions and copy the contents of the keybindings.json configuration file into the system keybindings file, which is initially empty. This ensures that the keyboard shortcuts, which maximize user comfort and experience, will work correctly.

Keyboard Shortcuts

  • Shift+F7: TASK MENU (standalone, library, both)
  • F7: 🔨 Quick build Standalone
  • F5: 🪲 Quick debug Standalone
  • Ctrl+Alt+R: just Launch Standalone binary
  • Ctrl+Alt+L: 🔍 clang-tidy
  • Ctrl+Alt+F: 📐 clang-format
  • Ctrl+Alt+M: 📏 cmake-format

Automatic Tasks

By Shift+F7 invoked TASK MENU includes the following automation commands:

  • 🚀 Zero to Build means 🧹 🗡️ 🔧 🔨
  • 🦸 Zero to Hero means 🧹 🗡️ 🔧 🔨 📌 🗜️
  • 🧹 Clean build directories
  • 🗡️ Dependency installation with Conan 2
  • 🔧 CMake configuration
  • 🪲 CMake configuration with CMake 🦉 debugger
  • 🔨 Build (Re-Build F7)
  • 📜 License collection with CPM for CPM
  • 📌 Install artefacts
  • 🗜️ Release tarballs
  • 🛸 Run CPack
  • ⚔️ Conan create library recipe
  • 📊 Conan dependencies in graph.html
  • 🔍 CLang-tidy
  • 📐📏 CLang & CMake formatting

CMake Build Options

Supports multiple build types as specified in tasks.json:

- Debug
- Release
- RelWithDebInfo
- MinSizeRel

Configurable CMake Options

The following CMake options can be configured to tailor the build process to your specific needs:

  • BUILD_SHARED_LIBS: Build shared libraries instead of static ones.
  • USE_STATIC_RUNTIME: Use the static runtime library.
  • SANITIZE_ADDRESS: Enable address sanitizer.
  • SANITIZE_UNDEFINED: Enable undefined behavior sanitizer.
  • SANITIZE_THREAD: Enable thread sanitizer.
  • SANITIZE_MEMORY: Enable memory sanitizer.
  • ENABLE_HARDENING: Enable hardening options for increased security.
  • ENABLE_IPO: Enable interprocedural optimization.
  • ENABLE_CCACHE: Enable ccache for faster recompilation.

These options provide flexibility and control over the build configuration, allowing you to optimize for performance, security, and development efficiency.

Manual Configuration and Build Options

Linux

Install Conan dependencies

conan install "." --output-folder="./build/standalone/default/debug" --deployer=full_deploy --build=missing --profile default --settings build_type=Debug

Configure Solution

source "./build/standalone/default/debug/conanbuild.sh" && cmake -S "./standalone" -B "./build/standalone/default/debug" -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX="./build/installation/default/debug"

Build Solution

source "./build/standalone/default/debug/conanbuild.sh" && cmake --build "./build/standalone/default/debug"  -j 16

Install Solution

source "./build/standalone/default/debug/conanbuild.sh" && cmake --build "./build/standalone/default/debug" --target install -j 16

Toolchains for Cross-Compilation

The solution includes a few predefined toolchain names that I actively use, so I decided to leave them in the template. The toolchain names match the profile names used via Conan 2. You can adjust them as needed. To start, it's good to know that default is the profile that Conan 2 creates first.

snippet from task.json

{
    "id": "buildArch",
    "type": "pickString",
    "description": "Select target architecture",
    "options": [
        "default", 
        "x86_64-clang-linux-gnu",
        "x86_64-w64-mingw32",
        "aarch64-rpi4-linux-gnu"
    ],
    "default": "default"
}

Maintenance

Renaming

Renaming the executable and library, including all necessary strings and classes, is handled by the Python script SolutionRenamer.py.

Update files of your choice from the repository

Updating individual files from the remote repository with the option to back up updated components is handled by the Python script SolutionUpgrader.py.

Log using history

Workflow activities related to the project are logged in the file Solution.log.

Additional Information on Template Structure

Folders

MarkWareVCMake/
├── include/ Contains **library project** public header files (.hpp) intended for use in other projects or modules.
MarkWareVCMake/
├── src/ Contains **library project** source files (.cpp) and `internal` header files (.hpp) that are not intended for public use.
MarkWareVCMake/
├── standalone/ Contains just **standalone** project.
MarkWareVCMake/
├── assets/ Contains project **assets**. All content included in this folder is accessible via file path by macro ASSET_PATH.

Argument Management for Standalone

The C++ source code uses a basic cxxopt implementation described below.

  • -o omit library loading
  • -h show help

FAQ

Q: Build task error
Error: /home/.../Build/Standalone/default/Debug is not a directory
Error: /home/.../Build/Library/default/Debug is not a directory
A: There is nothing to build. You must first create the configurations for the product, and only then can you compile separately with the build task. The "Zero to Build," "Zero to Hero," or CMake configuration tasks will help you create the configuration, which can then be compiled.

Q: CMake-tidy error
Error while trying to load a compilation database: Could not auto-detect compilation database from directory, etc.
A: For static code analysis to work correctly, you need to have the CMake configurations prepared. Also, ensure that the CMAKE_EXPORT_COMPILE_COMMANDS variable is set to ON in CMakeLists.txt.

Tips

Transform binary file to C source code under Linux

xxd -i file.bin > file.h

Thanks

To everyone who supported me in creating this template. These are various people and information from the web. Of course, also literature and courses that I have taken in the past. Various Discord servers and individuals who took a moment to make an indelible mark on this amazing work for me. Thank you very much!

Credits

tomasmark79, littlemushroom

License

MIT License Copyright (c) 2024-2025 Tomáš Mark

This project is licensed under the MIT License. No warranty of functionality or liability is provided. If you use this project, please mention my credentials. If you need software and technical support, you can contact me.