Skip to content

README.md

Latest commit

 

History

History
928 lines (643 loc) · 22.6 KB

README.md

File metadata and controls

928 lines (643 loc) · 22.6 KB

⬅ Back to main readme file

Pythonic C++ Library - Quick Start Guide

This guide shows you how to use the Pythonic C++ library in your own projects.

Table of Contents

Prerequisites

Before you begin, make sure you have:

  • C++20 compiler (GCC 10+, Clang 10+, MSVC 2019+)
  • CMake 3.10 or later
  • Git

Optional Dependencies (for media features)

To use terminal image/video rendering with print(), install:

  • ImageMagick - For image format conversion (PNG, JPG, etc.)
  • FFmpeg - For video decoding and playback

Linux (Debian/Ubuntu):

sudo apt update && sudo apt install -y imagemagick ffmpeg

Linux (Fedora):

sudo dnf install imagemagick ffmpeg

Linux (Arch):

sudo pacman -S imagemagick ffmpeg

macOS (Homebrew):

brew install imagemagick ffmpeg

Windows:

Download and install:

  • ImageMagick - Add to PATH during installation
  • FFmpeg - Add to PATH manually or use choco install ffmpeg

Verify Installation:

convert --version   # Should show ImageMagick version
ffmpeg -version     # Should show FFmpeg version

Optional: Audio Playback for Videos

To enable synchronized audio playback with videos, you need SDL2 or PortAudio:

Linux (Debian/Ubuntu):

# SDL2 (recommended)
sudo apt-get install libsdl2-dev

# Or PortAudio
sudo apt-get install portaudio19-dev libportaudio2

Linux (Fedora):

# SDL2 (recommended)
sudo dnf install SDL2-devel

# Or PortAudio
sudo dnf install portaudio-devel

Linux (Arch):

# SDL2 (recommended)
sudo pacman -S sdl2

# Or PortAudio
sudo pacman -S portaudio

macOS (Homebrew):

# SDL2 (recommended)
brew install sdl2

# Or PortAudio
brew install portaudio

Windows (vcpkg):

# SDL2 (recommended)
vcpkg install sdl2:x64-windows

# Or PortAudio
vcpkg install portaudio:x64-windows

Building with Audio Support:

# With SDL2
cmake -B build -DPYTHONIC_ENABLE_SDL2_AUDIO=ON
cmake --build build

# Or with PortAudio
cmake -B build -DPYTHONIC_ENABLE_PORTAUDIO=ON
cmake --build build

Audio Usage:

#include <pythonic/pythonic.hpp>
using namespace Pythonic;

// Play video with audio (Audio::on enables synchronized audio)
print("video.mp4", Type::video, Render::BW, Audio::on);

// Play video with audio in true color
print("video.mp4", Type::video, Render::colored, Audio::on);

// Default: video without audio
print("video.mp4", Type::video);  // Audio::off is default

Note: If audio libraries are not available, Audio::on will automatically fall back to silent video playback.

Optional: GPU-Accelerated Video Rendering

For smoother colored video playback (especially for high-resolution videos), you can enable OpenCL GPU acceleration:

Linux (Debian/Ubuntu):

sudo apt-get install ocl-icd-opencl-dev opencl-clhpp-headers

Linux (Fedora):

sudo dnf install ocl-icd-devel opencl-headers

Linux (Arch):

sudo pacman -S ocl-icd opencl-headers

macOS:

OpenCL is included with macOS by default - no additional installation needed.

Windows (vcpkg):

vcpkg install opencl:x64-windows

Building with GPU Support:

# Enable OpenCL when configuring
cmake -B build -DPYTHONIC_ENABLE_OPENCL=ON
cmake --build build

# Or combine with other options
cmake -B build -DPYTHONIC_ENABLE_SDL2_AUDIO=ON -DPYTHONIC_ENABLE_OPENCL=ON
cmake --build build

How It Works:

  • When OpenCL is enabled and a GPU is detected, colored video rendering uses GPU acceleration
  • The GPU processes frame data in parallel, reducing flickering and improving frame rates
  • If no GPU is available, it automatically falls back to optimized CPU rendering

Note: OpenCL support is completely optional. Video playback works without it, just with potentially more flickering on high-resolution colored videos.

Optional: True Simultaneous Key Detection (Linux)

For games and interactive applications that require detecting multiple keys pressed simultaneously, the TerminalGraphics keyboard system provides enhanced input handling.

How It Works:

  • Windows: Automatic via GetAsyncKeyState() - no setup required
  • macOS/Linux (default): Uses a 200ms "sticky window" for simulated multi-key detection
  • Linux (evdev): Optional direct hardware access for true simultaneous detection

Linux (evdev) Setup:

For true multi-key detection on Linux, you need:

  1. Read access to /dev/input/event* devices
  2. Define PYTHONIC_USE_EVDEV when compiling
# Add your user to the input group (log out and back in after)
sudo usermod -aG input $USER

# Compile with evdev support
g++ -std=c++20 -DPYTHONIC_USE_EVDEV -Iinclude -o game game.cpp -pthread

CMake Configuration:

# Enable evdev when configuring (Linux only, auto-detected)
cmake -B build -DENABLE_EVDEV=ON
cmake --build build

How to Use:

#include <pythonic/TerminalGraphics.hpp>
using namespace Pythonic::TG;

int main() {
    Keyboard::init();

    while (true) {
        // On Windows and Linux with evdev: true simultaneous detection
        // On other systems: simulated via sticky window
        if (Keyboard::isKeyPressed(Key::W) && Keyboard::isKeyPressed(Key::D)) {
            // Move forward-right diagonally
        }
    }

    Keyboard::shutdown();
}

Note: The terminal mode fallback (without evdev) still provides good multi-key simulation using a 200ms sticky window - most games will work fine without evdev.

Step 1: Clone the Pythonic Library

First, choose a location to install the Pythonic library (this can be anywhere on your system). For this guide, we'll use a folder called pythonic_cpp_lib:

Linux / macOS:

mkdir -p ~/pythonic_cpp_lib
cd ~/pythonic_cpp_lib
git clone https://github.com/Creamy-pie-96/Pythonic.git
cd Pythonic

Windows (Command Prompt):

mkdir %USERPROFILE%\pythonic_cpp_lib
cd %USERPROFILE%\pythonic_cpp_lib
git clone https://github.com/Creamy-pie-96/Pythonic.git
cd Pythonic

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path ~\pythonic_cpp_lib
cd ~\pythonic_cpp_lib
git clone https://github.com/Creamy-pie-96/Pythonic.git
cd Pythonic

Note: You can use any directory name and location you prefer - just remember where you put it!

Step 2: Build and Install the Library

Now build and install the Pythonic library. The install will be placed in a subfolder called install within the Pythonic directory.

Linux / macOS:

mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../install -DPYTHONIC_ENABLE_GRAPH_VIEWER=ON
cmake --build . --target install -j4
cd ../..    # Go back to pythonic_cpp_lib directory
pwd         # Remember this path - you'll need it later!

If you want to use the interactive Graph Viewer (`var::show()`), build
the library with graph viewer support enabled. This will compile the
GLFW/OpenGL/ImGui-backed viewer and expose the CMake target
`pythonic::pythonic_graph_viewer` for downstream projects.

Enable the viewer during configuration:

```bash
cmake .. -DCMAKE_INSTALL_PREFIX=../install -DPYTHONIC_ENABLE_GRAPH_VIEWER=ON
cmake --build . --target install -j4

Required system dependencies (example on Debian/Ubuntu):

sudo apt update && sudo apt install -y build-essential cmake libglfw3-dev libx11-dev \
    libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev libgl1-mesa-dev

ImGui is included in the Pythonic repository under external/imgui. If you vendor or replace it, ensure the viewer build picks up a compatible ImGui + OpenGL loader.

Platform notes and install hints

macOS (Homebrew)

# Install dependencies via Homebrew
brew update
brew install cmake glfw
# OpenGL is provided by the system (via frameworks). Build as usual with CMake.

Windows (Visual Studio + vcpkg)

Option A — vcpkg (recommended):

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.bat   # or bootstrap-vcpkg.sh on WSL

# Install GLFW and other deps for x64
./vcpkg install glfw3:x64-windows

# Configure CMake to use vcpkg toolchain when building your project
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_PREFIX_PATH=<path-to-pythonic-install>

Option B — Visual Studio without vcpkg:

  1. Install the "Desktop development with C++" workload in Visual Studio.
  2. Download prebuilt GLFW binaries or build GLFW from source and point CMake to the GLFW install location via CMAKE_PREFIX_PATH or -DGLFW_ROOT.

On Windows, OpenGL is available via opengl32.lib (FindOpenGL handles it).


### Windows (Command Prompt):

```cmd
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=..\install -DPYTHONIC_ENABLE_GRAPH_VIEWER=ON
cmake --build . --target install --config Release
cd ..\..
cd

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX="..\install"
cmake --build . --target install --config Release
cd ..\..
Get-Location    # Remember this path - you'll need it later!

After this step:

  • The library is installed at: <your-pythonic_cpp_lib-path>/Pythonic/install/
  • Save or remember this full path - you'll use it when building your own projects

Step 3: Create Your Project

Now create your own project in a separate location (anywhere you want - doesn't need to be near the Pythonic library):

Linux / macOS:

mkdir -p ~/myproject
cd ~/myproject

Windows (Command Prompt):

mkdir %USERPROFILE%\myproject
cd %USERPROFILE%\myproject

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path ~\myproject
cd ~\myproject

Your directory structure now looks like:

(anywhere on your system)
└── pythonic_cpp_lib/
    └── Pythonic/
        └── install/          ← Pythonic is installed here

(can be anywhere else on your system)
└── myproject/                ← Your project (we are here now)

Step 4: Write Your Code

Create two files in your project directory:

4.1: Create main.cpp

#include <pythonic/pythonic.hpp>

using namespace pythonic::vars;
using namespace pythonic::print;

int main() {
    var x = 42;
    var name = "Pythonic C++";

    print("Hello from", name);
    print("The answer is:", x);

    // Create a list
    var nums = list(1, 2, 3, 4, 5);
    print("Numbers:", nums);

    return 0;
}

Or you can also copy the demo.cpp from example dir

4.2: Create CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# Require C++20
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# If you plan to link the optional Graph Viewer (to enable `var::show()`),
# CMake needs to find OpenGL before importing the installed `pythonic`
# package because the exported viewer target references `OpenGL::GL`.
find_package(OpenGL REQUIRED)

# Find the Pythonic library
find_package(pythonic REQUIRED)

# Find ImageMagick and FFmpeg for media rendering support (images and videos)
find_package(ImageMagick COMPONENTS Magick++ REQUIRED)
find_package(PkgConfig REQUIRED)
pkg_check_modules(FFMPEG REQUIRED libavcodec libavformat libswscale libavutil)

# Optional: SDL2 for audio playback
pkg_check_modules(SDL2 QUIET sdl2)
if(SDL2_FOUND)
    message(STATUS "SDL2 found - audio playback enabled")
endif()

# Optional: OpenCL for GPU-accelerated video rendering
find_package(OpenCL QUIET)
if(OpenCL_FOUND)
    message(STATUS "OpenCL found - GPU acceleration enabled")
endif()

# Add your executable (replace main.cpp with your source files)
add_executable(myapp main.cpp)

# Link the Pythonic library and media dependencies
target_link_libraries(myapp PRIVATE pythonic::pythonic ImageMagick::Magick++ ${FFMPEG_LIBRARIES})

# Add FFmpeg include directories
target_include_directories(myapp PRIVATE ${FFMPEG_INCLUDE_DIRS})

# Link optional SDL2 for audio
if(SDL2_FOUND)
    target_compile_definitions(myapp PRIVATE PYTHONIC_ENABLE_SDL2_AUDIO)
    target_include_directories(myapp PRIVATE ${SDL2_INCLUDE_DIRS})
    target_link_libraries(myapp PRIVATE ${SDL2_LIBRARIES})
endif()

# Link optional OpenCL for GPU acceleration
if(OpenCL_FOUND)
    target_compile_definitions(myapp PRIVATE PYTHONIC_ENABLE_OPENCL)
    target_include_directories(myapp PRIVATE ${OpenCL_INCLUDE_DIRS})
    target_link_libraries(myapp PRIVATE ${OpenCL_LIBRARIES})
endif()

# If you built and installed Pythonic with the Graph Viewer enabled,
# link the viewer target to enable `var::show()` in your app:
target_link_libraries(myapp PRIVATE pythonic::pythonic_graph_viewer)

Copy paste it or we have a CMakeLists.txt file in example directory. You can directly use that too.

Step 5: Build Your Project

Now configure and build your project. You need to tell CMake where you installed the Pythonic library.

IMPORTANT - You Must Specify the Path:
Replace <path-to-pythonic-install> below with the actual full path to where you installed Pythonic in Step 2.

For example:

  • Linux/macOS: /home/username/pythonic_cpp_lib/Pythonic/install
  • Windows: C:\Users\username\pythonic_cpp_lib\Pythonic\install

Linux / macOS:

mkdir build
cd build

# Replace <path-to-pythonic-install> with your actual path!
# Example: cmake .. -DCMAKE_PREFIX_PATH=/home/john/pythonic_cpp_lib/Pythonic/install
cmake .. -DCMAKE_PREFIX_PATH=<path-to-pythonic-install>

cmake --build . -j4

Example with actual path:

cmake .. -DCMAKE_PREFIX_PATH=$HOME/pythonic_cpp_lib/Pythonic/install

Windows (Command Prompt):

mkdir build
cd build

REM Replace <path-to-pythonic-install> with your actual path!
REM Example: cmake .. -DCMAKE_PREFIX_PATH=C:\Users\John\pythonic_cpp_lib\Pythonic\install
cmake .. -DCMAKE_PREFIX_PATH=<path-to-pythonic-install>

cmake --build . --config Release

Example with actual path:

cmake .. -DCMAKE_PREFIX_PATH=%USERPROFILE%\pythonic_cpp_lib\Pythonic\install

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path build
cd build

# Replace <path-to-pythonic-install> with your actual path!
# Example: cmake .. -DCMAKE_PREFIX_PATH="C:\Users\John\pythonic_cpp_lib\Pythonic\install"
cmake .. -DCMAKE_PREFIX_PATH="<path-to-pythonic-install>"

cmake --build . --config Release

Example with actual path:

cmake .. -DCMAKE_PREFIX_PATH="$HOME\pythonic_cpp_lib\Pythonic\install"

Finding Your Path:

If you forgot where you installed Pythonic, you can find it:

Linux/macOS:

find ~ -name "pythonicConfig.cmake" 2>/dev/null
# This will show the full path - use everything before "/lib/cmake/pythonic/"

Windows (PowerShell):

Get-ChildItem -Path $HOME -Filter "pythonicConfig.cmake" -Recurse -ErrorAction SilentlyContinue
# Look for the path, use everything before "\lib\cmake\pythonic\"

Step 6: Run Your Application

Using the Graph Viewer (var::show())

If you built and installed Pythonic with -DPYTHONIC_ENABLE_GRAPH_VIEWER=ON, your installed package exports the target pythonic::pythonic_graph_viewer. Link that target in your project's CMakeLists.txt to enable the interactive viewer API. Example CMake configuration:

find_package(pythonic REQUIRED)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE pythonic::pythonic pythonic::pythonic_graph_viewer)

Minimal example that uses the viewer:

#include <pythonic/pythonic.hpp>
using namespace pythonic::vars;

int main() {
        var g = graph(3);
        g.add_edge(0, 1, 1.0, 0.0, true);
        g.add_edge(1, 2, 1.0, 0.0, true);

        // Show opens an interactive window (may block until closed)
        g.show();

        return 0;
}

Runtime notes:

  • The viewer opens a desktop window: ensure a graphical session (DISPLAY) is available on Linux. Headless servers without an X/Wayland display cannot show the GUI unless you use a virtual framebuffer (Xvfb).
  • If you see missing link symbols when building your application, confirm system GLFW/OpenGL development packages were available when Pythonic was built and that Pythonic was installed with the viewer enabled.

Finally, run your compiled program:

Linux / macOS:

./myapp

Windows (Command Prompt):

Release\myapp.exe

Windows (PowerShell):

.\Release\myapp.exe

You should see output like:

Hello from Pythonic C++
The answer is: 42
Numbers: [1, 2, 3, 4, 5]

Alternative: Using Without Installing

If you don't want to install the library, you can include the headers directly:

CMakeLists.txt (Direct Include Method)

cmake_minimum_required(VERSION 3.10)
project(MyApp)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find optional dependencies
find_package(PkgConfig QUIET)
if(PKG_CONFIG_FOUND)
    pkg_check_modules(SDL2 QUIET sdl2)
endif()
find_package(OpenCL QUIET)

add_executable(myapp main.cpp)

# Point directly to the Pythonic include directory
target_include_directories(myapp PRIVATE
    ${CMAKE_SOURCE_DIR}/../Pythonic/include
)
target_compile_features(myapp PRIVATE cxx_std_20)

# Optional: SDL2 for audio playback
if(SDL2_FOUND)
    target_compile_definitions(myapp PRIVATE PYTHONIC_ENABLE_SDL2_AUDIO)
    target_include_directories(myapp PRIVATE ${SDL2_INCLUDE_DIRS})
    target_link_libraries(myapp PRIVATE ${SDL2_LIBRARIES})
    message(STATUS "SDL2 audio enabled")
endif()

# Optional: OpenCL for GPU acceleration
if(OpenCL_FOUND)
    target_compile_definitions(myapp PRIVATE PYTHONIC_ENABLE_OPENCL)
    target_include_directories(myapp PRIVATE ${OpenCL_INCLUDE_DIRS})
    target_link_libraries(myapp PRIVATE ${OpenCL_LIBRARIES})
    message(STATUS "OpenCL GPU acceleration enabled")
endif()

Then build without CMAKE_PREFIX_PATH:

Linux / macOS:

mkdir build && cd build
cmake ..
cmake --build . -j4
./myapp

Windows (Command Prompt):

mkdir build && cd build
cmake ..
cmake --build . --config Release
Release\myapp.exe

Troubleshooting

"Could not find pythonic" Error

This is the most common error. It means CMake cannot find the installed package config files.

Solution:

  1. Find where you installed Pythonic:

    Linux/macOS:

    find ~ -name "pythonicConfig.cmake" 2>/dev/null

    This will show something like: /home/user/pythonic_cpp_lib/Pythonic/install/lib/cmake/pythonic/pythonicConfig.cmake

    The path you need is everything before /lib/cmake/pythonic/:
    → /home/user/pythonic_cpp_lib/Pythonic/install

    Windows (PowerShell):

    Get-ChildItem -Path $HOME -Filter "pythonicConfig.cmake" -Recurse -ErrorAction SilentlyContinue

    This will show something like: C:\Users\John\pythonic_cpp_lib\Pythonic\install\lib\cmake\pythonic\pythonicConfig.cmake

    The path you need is everything before \lib\cmake\pythonic\:
    → C:\Users\John\pythonic_cpp_lib\Pythonic\install

  2. Use that full path in your cmake command:

    cmake .. -DCMAKE_PREFIX_PATH=/home/user/pythonic_cpp_lib/Pythonic/install

    note you can add -DCMAKE_BUILD_TYPE=Release if you want to build in release mode

  3. Verify the path is correct before running cmake:

    Linux/macOS:

    ls /path/to/pythonic_cpp_lib/Pythonic/install/lib/cmake/pythonic/
# Should show: pythonicConfig.cmake  pythonicConfigVersion.cmake  pythonicTargets.cmake

    Windows:

    dir C:\path\to\pythonic_cpp_lib\Pythonic\install\lib\cmake\pythonic\

"pythonic/pythonic.hpp: No such file or directory"

  • Check that you're using pythonic::pythonic (with ::) in target_link_libraries
  • Verify headers were installed to install/include/pythonic/

Compiler Errors about C++20

  • Ensure your compiler supports C++20
  • On older systems, you may need to update GCC/Clang

Optional: Enabling Graphviz Support

The Graph class includes a to_dot() method that exports the graph structure to a DOT file (for visualization with Graphviz). By default, it only creates the .dot file.

If you have Graphviz installed on your system, you can enable automatic SVG generation when to_dot() is called.

Auto-Detection (Recommended)

The CMakeLists.txt provided in this examples folder automatically detects Graphviz. When you run cmake, you'll see one of these messages:

-- Graphviz found: /usr/bin/dot
--   Graph::to_dot() will automatically generate SVG files

or:

-- Graphviz not found (optional)
--   Graph::to_dot() will only create .dot files
--   Install Graphviz to enable automatic SVG generation

To disable the auto-detection, configure with:

cmake .. -DCMAKE_PREFIX_PATH=<path> -DENABLE_GRAPHVIZ=OFF

Manual Enable (Alternative)

If you're creating your own CMakeLists.txt from scratch, add this line after add_executable():

target_compile_definitions(myapp PRIVATE GRAPHVIZ_AVAILABLE)

Or define it in your code before including the library:

#define GRAPHVIZ_AVAILABLE
#include <pythonic/pythonic.hpp>

Example Usage

#include <pythonic/pythonic.hpp>

using namespace pythonic::vars;

int main() {
    var g = graph(4);
    g.add_edge(0, 1, 1.0);
    g.add_edge(1, 2, 2.0);
    g.add_edge(2, 3, 3.0);
    g.add_edge(3, 0, 4.0);

    // If GRAPHVIZ_AVAILABLE: Creates my_graph.dot AND my_graph.svg
    // Otherwise: Creates only my_graph.dot
    g.to_dot("my_graph.dot");
    return 0;
}

Without Graphviz installed, you can still manually convert DOT files:

# Install Graphviz first (one-time):
# Ubuntu/Debian: sudo apt install graphviz
# macOS: brew install graphviz
# Windows: Download from https://graphviz.org/download/

# Then convert manually:
dot -Tsvg my_graph.dot -o my_graph.svg
dot -Tpng my_graph.dot -o my_graph.png

What's Next?

Check out the full documentation in the Documentation for all the features:

  • Dynamic typing with var
  • Python-style containers (lists, dicts, sets)
  • Slicing, comprehensions, ranges
  • Graph algorithms
  • Math library
  • And much more!

Enjoy coding with Pythonic C++!