proj. Hex++

C++ project manager. Wrapper to combine CMake, vcpkg, and project generation.

Made to ease your C++ project management with a bit of hex magix ~

---

https://github.com/Katacc/hexpp (main)
https://gitlab.com/Katacc/hexpp

Release and plans

Hello! Im proud to release my take on C++ project management for the public!

The project is in working state and has the core functionalities I wanted it to have. There shouldn't be any big changes that would break projects, but I can't say for sure yet. Ill let you know if any updates comes that might break functionality, and how to migrate

TODO:

• Argument passing for the target runnable
• Intuitive way to include libraries in the configuration file
• "self-heal" command
• Regex matching for configurations to everywhere, currently configs are strict on spacing

Getting Started

Prerequisites

This project uses CMake, GCC, and G++ compilers, which can be installed natively on Linux and macOS or through MSYS2 for Windows.

Required Tools:

• g++ or clang (c++23 support)
• gcc or clang
• gdb
• CMake (4.0 or later recommended, building hex++ requires 3.31)
• Make
• vcpkg (installation guide below)
• ninja

NixOS

For NixOS users, there is a flake included to be able to build hx++ and do simple C++ development

Windows-Specific Requirements:

If you are on Windows and want to use the default vcpkg compiler settings, you need to have MSVC (Microsoft Visual C++ Compiler) installed.

---

Installing vcpkg

vcpkg is a C/C++ package manager made by Microsoft: https://vcpkg.io. You can follow the guide on their website or use the steps below.

Steps to Install vcpkg:

1. Clone the repository:

   git clone https://github.com/microsoft/vcpkg.git
   

2. Run the bootstrap script:

   • Linux/macOS:

     cd vcpkg && ./bootstrap-vcpkg.sh
     

   • Windows:

     cd vcpkg
     .\bootstrap-vcpkg.bat
     

3. Configure the VCPKG_ROOT environment variable: Add your vcpkg root directory to your PATH. For example:

   export VCPKG_ROOT=/path/to/vcpkg
   export PATH=$VCPKG_ROOT:$PATH
   

   Note

   Consider adding it permanently to your PATH and creating a new environment variable VCPKG_ROOT.

---

Building Hex++

1. Clone the repository:

   git clone https://github.com/Katacc/hexpp.git
   cd hexpp
   

2. Use CMake to build the project (gcc):

   • Default Preset (gcc):

   cmake --preset=default
   cmake --build build --config Release
   

If it fails, try to force gcc profile

cmake --preset=gcc
cmmake --build build --config Release

3. clang users:

   • clang Preset:

   cmake --preset=clang
   cmake --build build --config Release
   

4. Locate the executable: The executable will be located in the build/Release folder. You can copy it to your PATH to use it anywhere.

   • Linux Example:

   chmod +x ./build/Release/hx++
   sudo cp ./build/Release/hx++ /usr/bin/
   

   • Windows Example: Copy the build/Release/hx++.exe to a folder (e.g., bin) and add that folder to your PATH.

Find writing hx++ annoying?

After cloning hexpp repository, go into project.cfg, and change the project name to hxpp, this makes the executable into hxpp(.exe)

[project]
name = hxpp
version = 1.0.0

[CMake]
CXX_version = 23

if you have built the project allready with the original name, don't worry, just delete /build folder and build again after changing the value in project.cfg

---

Using Hex++

Hex++ is a C++ project manager that creates and initializes a C++ project for you, it can build, run and add packages.

Project Structure:

When you create a new project, it will have the following structure:

project
│
├── build/                  # Build files (generated by CMake)
│
├── .vscode/                # VSCode configuration files
│   ├── tasks.json          # Build tasks
│   ├── launch.json         # Debug configurations
│
├── src/                    # Source code
│   ├── main.cpp            # Main entry point of the application
│   ├── libraries/          # Header-only libraries
│   │   └── test.h          # Example library file
│
├── project.cfg             # Stores the project name and version
├── CMakeLists.txt          # CMake configuration file
├── CMakePresets.json       # CMake presets for build configurations
├── CMakeUserPresets.json   # User-specific CMake presets
├── .gitignore              # Git ignore file
└── vcpkg.json              # vcpkg package configuration

Commands:

1. Create a New Project:

   hx++ new <project_name>
   cd <project_name>
   

2. Build the Project:

   hx++ build [config] [preset]
   

   Example:

   hx++ build     # Builds the project with Debug and default preset
   

3. Run the Project Executable:

   hx++ run [config]
   

   You can also pass arguments to the target program:

   hx++ run [config] <arguments>
   

4. Add a Package Through vcpkg:

   hx++ add <package>
   

   Example:

   hx++ add sdl3
   

5. Search for package through vcpkg:

   hx++ search <package>
   

   Install packages : (Not necessary, it installs them when running first build anyways)

   hx++ install
   

   After adding a package, vcpkg will show you what to add to your CMakeLists.txt. You need to manually include it in. For example:

   -- From shell after running hx++ add sdl3

   sdl3 provides CMake targets:
   
   find_package(SDL3 CONFIG REQUIRED)
   target_link_libraries(main PRIVATE SDL3::SDL3)
   

   -- Add to your CMakeLists.txt

   find_package(SDL3 CONFIG REQUIRED)
   target_link_libraries([PROGRAM_NAME] PRIVATE
                            # Installed libraries here
                            SDL3::SDL3
                        )
   

---

Configuring

If configurations are not set, file not found or other reasons, the program defaults to its set default values, to use gcc and g++ and default profile for building.

Default profile uses CXX_COMPILER_PATH and C_COMPILER_PATH

Hex++ can be configured with a configuration file. To do so, create new folder hex++ in your ~/.config and add a file config.ini there

~ = User home folder

~/.config/hex++/config.ini

Following configurations are available, the first three configs impacts the custom build preset and the last configuration value sets your default preset the build command uses. The configurations does not affect default, vcpkg or clang profiles!

eg: default_preset = clang This uses clang preset by default on build, if you don't specify parameters

CXX_COMPILER_PATH = clang++
C_COMPILER_PATH = clang
C_DEBUGGER_PATH = gdb

default_preset = default

Note, pay attention to the syntax (correct spacing)
Note2, add an empty line after configurations just in case!

---

Changing C++ version

Change the variable in project.cfg
CXX_version default will be 23

changing CMake version will be done the CMake way in CMakeLists.txt

---

Adding Files to the Project

Header-Only Files:

To add header-only files (.h), place them in the libraries folder and include them in your source files:

#include "test.h"

Header + Implementation Files:

CMake is configured to find all .cpp files and automatically added to the project, if using recent enough CMake version. (4.0 recommended)

include header files in your source files normally. Use absolute paths from src

// In main.cpp
#include "commands/headers/test.h"

Modules

Adding modules is simple, CMake automatically grabs all module files (.cppm and .ixx) ((.cppm is advised, not all editors recognize .ixx)) and includes them for you, you only need to do the standard C++23 module exports and imports in your program.

If you use modules, I suggest using Clang, GCC has some problems with modules still.

Quick example of modules in C++23

// testmod.cppm

module;
#include <iostream>     // Old header includes are to be done 
                        // inside of the module declaration zone.

export module testmod;  // Start of the module


// export keyword to make the function accessible outside.
export void print() {
    std::cout << "Print!" << std::endl;
}

// main.cpp
#include <iostream>
import testmod;

int main() {
    using namespace std;

    cout << "Test" << endl;

    print();    // The testmod print function.

    return 0;
}

---

Changing the Project Name and version

To change the project name:

1. Update the project.cfg file with the new name.
2. Update the project.cfg file with the new version

[project]
name = project_name
version = 1.0

---

Encountering Errors

Common Issues:

1. Build Errors:

   • Delete the build folder and try again:

     rm -rf build/
     hx++ build
     

2. Switching Between presets:

   • You must delete the build folder before switching:

     rm -rf build/
     

3. Missing Dependencies:

   • Ensure all required tools (e.g., gcc, g++, ninja) are installed and available in your PATH.

Reporting Issues:

If you encounter unexpected errors, please submit an issue describing the problem.

Preferably use GitHub for any issues / pull requests https://github.com/Katacc/hexpp

---

Example Workflow

1. Create a new project:

   hx++ new my_project
   cd my_project
   

2. Add a package:

   hx++ add sdl3
   

3. Build the project:

   hx++ build
   

4. Run the project:

   hx++ run
   

---

project.cfg syntax

project.cfg syntax is strict, since many things read from it, make sure the that there is 1 space in between values and = marks. (No regex matching for now)

[project]
name = hx++
version = 1.0.0

[CMake]
CXX_version = 23

---

Specific package problems

if you find a package thats problematic (and even maybe a fix) open issue in GitLab

• fmt

  • problem: refuses to compile
  • fix: Use fmt-header-only

• sdl3-image

  • problem: No png support
  • fix: install it using png flag sdl3-image[png]

---

Enjoy using Hex++!