Multi-Project Workspace Template

C/C++ Cross-Platform Multi-Project Template

About

This project is my best current & continuous effort at a portable C++ multi-project environment (without CMake!)
This Project aims to work seamlessly across Linux & Windows
Current Integration of tools:

• clangd
• ASan
• UBSan
• clang-format
• clang-tidy
• lldb
• Various useful C++ Libraries
  • ImGui
  • GLFW
  • glbinding
  • Catch2
  • GoogleMock & GoogleTest
  • Google Benchmark

Considerations

The original motivation was mainly the continuous discomfort with using hand-made Makefiles without recompilation targets, I had to recompile everything on every little change
More recently, I needed integration with various libraries & tools on vscode
I also needed some form of cross platform Support (Incoming DLL Hell) (Also see ABI Hell), so I eventually (unfortunately) decided I'll manage dependencies manually in a mono-repository (for now).

Considering the problem of build/meta-build systems, I examined multiple choices (found below) and eventually decided to use premake5 because of its relative simplicity to the competition:

• Make - Will not go back to those, too cumbersome to manage manually
• CMake - Industry standard, everyone loves to hate it
• xmake - Didn't need an alternative to cmake
• premake5 - A meta build system with lua syntax (also like xmake, except more barebones)
• Bazel - Seemed a little too much & too complex for what I needed
• Ninja - I do not know of any particular examples of people writing ninja scripts manually

Moreover, With the complexity involved in managing updates across multiple projects, when each of which uses this specific Mono-Repository and constantly changes/updates it, I've decided to move each Library here to its separate 'premake5-packaged' repository, with the eventual integration of git submodules to the library-consuming project

Project Structure

Each Project contains a premake5.lua file, describing everything about its compilation/linking
There are 5 sub-project lua files available as reference/guiding points if you don't understand the Explanation below

To add a project to compilation/linking:

• Create a premake5.lua file in your project root folder (see examples)
• Add project path to PROJECT_LIST in premake5.lua
• Specify a LinkMyLibraryName function in dir.lua (see LinkLibExampleLibrary() for more info)
• Use IncludeProjectHeaders(...) & LinkMyLibraryName in your other libraries/executables' (see sample/premake5.lua for more info)

To add a dependency (Header Only library, prebuilt shared/static library, etc...) to compilation/linking:

• Add the library to dependencies/
• Specify 2 functions in dir.lua:
  • LinkMyDependencyName
  • IncludeDependencyNameHeaders
• Use Them in your library/executables' premake5.lua

Built With

Getting Started

Prerequisites

1. premake5
2. Windows/Linux:
   • Windows:
   • Msys2 Clang64
   • Clang LLVM
     • [NOTE]: There may be compilation errors with Clang LLVM due to <threads.h>
   • Linux:
   • Installing a specific llvm version
   • Configure Symlinks - as clang-'version_number' will not be detected by premake5
3. Add your toolchain to the global PATH
4. [NOTE]: LLVM-Clang relies on Platform-Specific System Headers & Libraries
   • Windows: Standard Library implementation with System-Headers:
     • MSYS2 (use clang-mingw64 instead of LLVM-Clang)
     • MinGW-w64
     • WinLibs
     • MSVC (libraries will be automatically detected)
   • Linux: Will very likely work out of the box
5. Bash Shell
   • Windows:
   • Git for Windows
   • MSYS2 Clang64 Shell (Using MSYS2 without the provided terminal causes program execution issues with DLL's)
   • Linux:
   • Use your favourite Bash Shell

Installation

There are 4 branches available:

• with-subprojects - Includes ImGui, GLFW, glbinding, various homebrew Utility Libraries [awc2, util2], with a sample opengl compute program
• barebones - Executable-With-Library Sample, including reference premake files for:
  • ImGui
  • GLFW
  • glbinding
  • awc2 & util2 (My own Utility Libraries)
• GoogleBenchmark - like barebones, except with google-benchmark and a running example
• GoogleTest-Mock - like barebones, except with google-test & google-mock and a running example

# If you want everything
git clone -b with-subprojects https://github.com/inonitz/premake5-workspace-template.git
# If you prefer to configure on your own
git clone -b barebones https://github.com/inonitz/premake5-workspace-template.git
# Don't forget to add your own remote repo
git remote set-url origin your_github_username/premake5-workspace-template
git remote -v

Usage

call premake5 --help in the root of the repository

Common Commands:

    premake5 cleanproj --proj=program 
    premake5 cleanbuild
    premake5 cleancfg
    premake5 cleanclangd
    premake5 cleanall 
    premake5 export-compile-commands
    premake5 ecc (same as export-compile-commands)
    premake5 --os=windows --arch=x86_64 --cc=clang gmake
    premake5 --os=windows --arch=x86_64 --cc=clang ninja
    premake5 --os=windows --arch=x86_64 --cc=clang vs2022
    premake5 --os=linux --arch=x86_64 --cc=clang gmake
    premake5 --os=linux --arch=x86_64 --cc=gcc gmake

Roadmap

• Supporting VS2022 Project Solutions (they do not generate correctly)
• Generating a launch.json at Project-Generation Time
• Deleting files based on architecture (e.g cleanarch --arch='x')
• Generating Test-Unit Projects for each library (see prototype premake5_generate_unit_test_per_tu.lua)
• Adding an action to update compile_commands.json based on target
• Integrating Cppcheck
• Integrating a cross-platform C++ profiler With Flame Graphs - Tracy(?)/Optick(?)/(?)
• Cross-platform package management - Spack(?)
• Integration of LLVM Machine-Code Analyzer
• Utilizing Profile-Guided Optimization
• Automating this whole thing with Dev-Containers & Docker (Several issues, one being very gpu-specific solutions from every vendor)
• Optimization of Project-Generation Time:
  • with-subprojects branch
    • gmake
      • ~3200ms [windows]
      • ~2200ms [wsl2]
    • ninja
      • ~3100ms [windows]
      • ~2800ms [wsl2]
  • barebones branch
    • gmake
      • ~120ms [windows]
      • ~TBD [wsl2]
    • ninja
      • ~120ms [windows]
      • ~TBD [wsl2]

Contributing

If you have a suggestion, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

License

Distributed under the MIT License. See LICENSE file.

Acknowledgements

• Kumodatsu For the initial template repo
• Jarod42 For the Improvements branch of export-compile-commands
• Premake Ninja - Ninja Build System integration with premake5
• Best-README