Home

Awesome

CXX

Standard License

Make modern C++ easier to deal with.

Have you ever had a single main.cpp file that you just want to compile, without having to make sure the order of flags are correct and ideally without having to provide any flags at all?

cxx may fit your use case, provided you have scons, python and all required libraries for your project installed.

It should be possible to compile most of the examples in the examples directory, simply by running cxx in each directory.

Using cxx is simple:

No configuration files are needed, but the projects needs to either be very simple (a single main.cpp) or have a cxx-friendly directory structure.

The auto-detection of external libraries and headers relies on them being included in the main source file.

Tested on Arch Linux, FreeBSD, Ubuntu, macOS w/Homebrew, Void Linux and NetBSD. Docker images and Vagrant configuration files are available in the tests directory. Please submit a pull request if you have improvements for your platform!

Several examples are included in the examples directory. These mostly center around everything you would need to create a game in C++20: OpenGL, SDL2, Vulkan, Audio etc, but also includes examples for GTK 4, Qt 6, X11 and Windows (the example should build and run on Linux, using wine).

The target audience is programmers that don't want to fiddle with makefiles, CMake etc, but want to either try out a feature in C++20, learn modern C++ or create a demoscene demo or a game.

As much as possible is auto-detected. As long as the right packages are installed, and includes are specified in the main source file, all dependencies, libraries and build flags should be handled automatically.

cxx provides a way to structure your C++ code, test and debug your source files. It also makes it easy for Linux (or Homebrew) packagers to package your project, and for users to build and install it.

If you're an experienced C or C++ user and wish to write and distribute a C++ library (as opposed to an executable), just using CMake might be a better fit.

(This repository was created three years before dtolnay/cxx).

Packaging status

Packaging status

Installation

If cxx is available by using your favorite package manager, that's usually the best way.

Manual installation

First install cxx, so that it is in the path. Here is one way, using git clone, GNU Make and sudo:

git clone https://github.com/xyproto/cxx
cd cxx
make
sudo make install

Debian-based distros

For Debian or Ubuntu, these dependencies are recommended, for building CXX and most of the examples:

build-essential figlet freeglut3-dev g++-mingw-w64-x86-64 git gtk+3-dev libboost-all-dev libc-dev libglew-dev libglibmm-2.4-dev libsdl2-dev libsfml-dev make mesa-common-dev qtbase5-dev qt5-default qtdeclarative5-dev scons python3 apt-utils apt-file libconfig++-dev libconfig++ libopenal-dev libglfw3-dev libvulkan-dev libglm-dev libsdl2-mixer-dev libboost-system-dev libfcgi-dev

FreeBSD

For FreeBSD, here is one way of installing only the basic dependencies and CXX:

pkg install -y bash git gmake pkgconf python3 scons
git clone https://github.com/xyproto/cxx
cd cxx
gmake

Then as root:

gmake install

NetBSD

One way of installing CXX and also the libraries needed by most of the example projects:

pkgin -y install bash git gmake pkgconf python37 SDL2 SDL2_image SDL2_mixer SDL2_net SDL2_ttf docker freeglut gcc7 glew glm glut openal qt5 scons boost fcgi
test -d cxx && (cd cxx; git -c http.sslVerify=false pull origin main) || git -c http.sslVerify=false clone 'https://github.com/xyproto/cxx'
gmake -C cxx install

Void Linux

Installing CXX and the libraries needed by most of the example projects:

xbps-install -v -Sy SDL2-devel SDL2_mixer-devel SFML-devel boost-devel figlet gcc git glew-devel gtk+3-devel libconfig++-devel libfreeglut-devel libopenal-devel make pkg-config python3 qt5-devel scons fcgi
git clone https://github.com/xyproto/cxx && cd cxx && make install

Arch Linux

Just install cxx from AUR.

Example Use

Try out CXX and a small program that uses features from C++20

Create a main.cpp file:

#include <cstdlib>
#include <iomanip>
#include <iostream>
#include <ostream>
#include <string>

using namespace std::string_literals;

class Point {
public:
    double x;
    double y;
    double z;
};

std::ostream& operator<<(std::ostream& output, const Point& p)
{
    using std::setfill;
    using std::setw;
    output << "{ "s << setfill(' ') << setw(3) << p.x << ", "s << setfill(' ') << setw(3) << p.y
           << ", "s << setfill(' ') << setw(3) << p.z << " }"s;
    return output;
}

Point operator+(const Point& a, const Point& b)
{
    return Point { .x = a.x + b.x, .y = a.y + b.y, .z = a.z + b.z };
}

Point operator*(const Point& a, const Point& b)
{
    return Point { .x = a.x * b.x, .y = a.y * b.y, .z = a.z * b.z };
}

int main(int argc, char** argv)
{
    // designated initializers
    Point p1 { .x = 1, .y = 2, .z = 3 };
    Point p2 { .y = 42 };

    using std::cout;
    using std::endl;

    cout << "     p1 = " << p1 << endl;
    cout << "     p2 = " << p2 << endl;
    cout << "p1 + p2 = " << p1 + p2 << endl;
    cout << "p1 * p2 = " << p1 * p2 << endl;

    return EXIT_SUCCESS;
}

Then build the project with just:

cxx

Rebuilding can be done with:

cxx rebuild

Both building and running can be done with:

cxx run

If you wish to optimize the program, running it in a way that also records profiling information can be done with:

cxx rec

The next time the project is built, the profiling information is used to optimize the program further:

cxx

Other commands

Building files ending with _test.cpp, then running them

cxx test

Cleaning

cxx clean

Building with clang++ instead of g++:

cxx clang

Building a specific directory

cxx -C examples/hello

Installing on the local system, using sudo:

sudo PREFIX=/usr cxx install

Either main.cpp or the C++ source files in the current directory will be used when building with cxx.

Packaging a project into $pkgdir:

DESTDIR="$pkgdir" PREFIX=/usr cxx install

Packaging a project into a directory named pkg:

cxx pkg

Build a small executable:

cxx small

Build an executable with optimization flags turned on:

cxx opt

Strict compilation flags (complains about all things):

cxx strict

Sloppy compilation flags (will ignore all warnings):

cxx sloppy

Get the current version:

cxx version

Directories

Testing

Defines

These defines are passed to the compiler, if the corresponding paths exist (or will exist, when packaging):

(application_name is just an example).

This makes it easy to have an img, data or resources directory where files can be found and used both at development and at installation-time.

See examples/sdl2 and examples/win64crate for examples that uses IMGDIR.

See examples/mixer for an example that uses RESOURCEDIR.

An alternative method to using defines (defined with -D when building) is to use something like SDL_GetBasePath(). Example: res_path.h.

Features and limitations

Suggested directory structure

For a "Hello, World!" program that places the text-generation in a string hello() function, this is one way to structure the files, for separating the code into easily testable source files:

.
├── hello/main.cpp
├── hello/include/hello.h
├── hello/include/test.h
├── hello/common/hello.cpp
└── hello/common/hello_test.cpp

--- or if you prefer one directory per executable ---

.
└── hello/hello1/main.cpp
└── hello/hello2/main.cpp
└── hello/include/hello.h
└── hello/include/test.h
└── hello/common/hello.cpp
└── hello/common/hello_test.cpp

main.cpp

#include <iostream>
#include "hello.h"

int main()
{
    std::cout << hello() << std::endl;
    return 0;
}

hello.h

#pragma once

#include <string>

std::string hello();

hello.cpp

#include "hello.h"

using namespace std::literals;

std::string hello()
{
    return "Hello, World!"s;
}

hello_test.cpp

#include "test.h"
#include "hello.h"

using namespace std::literals;

void hello_test()
{
    equal(hello(), "Hello, World!"s);
}

int main()
{
    hello_test();
    return 0;
}

test.h

#pragma once

#include <iostream>
#include <cstdlib>

template<typename T>
void equal(T a, T b)
{
    if (a == b) {
      std::cout << "YES" << std::endl;
    } else {
      std::cerr << "NO" << std::endl;
      exit(EXIT_FAILURE);
    }
}

Requirements

Optional requirements

C++20 on macOS

For installing a recent enough version of C++ on macOS, installing gcc 11 with brew is one possible approach:

brew install gcc@11

The other requirements can be installed with:

brew install scons make pkg-config

C++20 on Arch Linux

g++ with support for -std=c++20 should already be installed.

Install scons and base-devel, if needed:

pacman -S scons base-devel --needed

C++20 on Debian or Ubuntu

You might need to install GCC 11 from the testing repository, or from a PPA.

Install build-essential, scons and pkg-config:

apt install build-essential scons pkg-config

C++20 on FreeBSD

FreeBSD 11.1 comes with C++17 support, but you may wish to install GCC 11 or later.

gcc11 or later should provide support for C++20.

Install pkg-conf, scons and gmake:

pkg install pkgconf scons gmake

Installation

Manual installation with make and sudo:

sudo make install

On FreeBSD, use gmake instead of make.

If possible, install CXX with the package manager that comes with your OS/distro.

Uninstallation

sudo make uninstall

One way of structuring projects

Filenames

Ninja

QtCreator

The generated qmake/QtCreator project files were tested with QtCreator 4.6 on Arch Linux.

Source code formatting

Feedback

The goal is that every executable and project written in C++20 should be able to build with cxx on a modern Linux distro, FreeBSD or macOS system (with Homebrew), without any additional configuration.

If you have a project written in C++ that you think should be able to build with cxx, but doesn't, please create an issue and include a link to your repository.

GNU Parallel

If running CXX with parallel, make sure to use the --compress or --tmpdir flag to change the location of the temporary SQLite database.

Example build target in a Makefile, for using parallel and cxx, while disabling warnings:

build:
    +CXXFLAGS='$(CXXFLAGS) -w' parallel --compress cxx opt -C ::: subdir1 subdir2 subdir3

subdir1, subdir2 and subdir3 are just examples of directory names.

OpenBSD

For OpenBSD, install g++ 11 and build with cxx CXX=eg++.

GTK and Qt

Editor Configuration

Syntastic settings for ViM and NeoVim:

" If your compiler does not support -std=c++20, it is possible to use -std=c++2a, -std=c++2b or -std=c++17.
let g:syntastic_cpp_compiler = 'g++'
let g:syntastic_cpp_compiler_options = ' -std=c++20 -pipe -fPIC -fno-plt -fstack-protector-strong -Wall -Wshadow -Wpedantic -Wno-parentheses -Wfatal-errors -Wvla'
let g:syntastic_cpp_include_dirs = ['../common', './common', '../include', './include']

" Ignore some defines and warnings
let g:syntastic_quiet_messages = {
    \ "!level": "errors",
    \ "regex":  [ 'RESOURCEDIR', 'RESDIR', 'DATADIR', 'IMGDIR', 'SHAREDIR', 'SHADERDIR', 'expected .*).* before string constant' ] }

General info