cmeel-boost: Boost C++ Libraries for CMake-based Python Wheels

Warnings

• gotcha cmeel-boost is a distribution of the *C++ Boost libraries* for `cmeel`-based Python wheels, not a Python wrapper library. You cannot `import cmeel_boost` in Python code and expect to access Boost C++ functionality directly through Python functions or classes. Its purpose is to provide the underlying C++ headers and compiled libraries for other C++/Python projects to link against.
  Fix: Do not attempt to `import cmeel_boost` to use Boost C++ features directly in Python. Instead, use `cmeel-boost` as a build dependency for your C++/Python project and interact with Boost in your C++ source code.
• breaking Building projects that depend on `cmeel-boost` (and thus `cmeel` and CMake) requires a robust C++ development environment, including a compatible C++ compiler and CMake. Build failures can occur due to missing toolchains, incorrect compiler versions, or environment misconfigurations, especially on Windows where `pip install` can be challenging for such projects.
  Fix: Ensure your system has a fully configured C++ development environment (e.g., Visual Studio Build Tools on Windows, `build-essential` on Linux) and a recent version of CMake. On Windows, `conda` is often recommended over `pip` for installing packages with complex C++ build dependencies.
• gotcha When consuming `cmeel-boost` in your CMake project, ensure you use `find_package(Boost REQUIRED COMPONENTS ...)` correctly. While `cmeel-boost` provides the Boost libraries, CMake still needs to be instructed to find them and link them to your targets. Issues can arise if the Boost version requested by `find_package` is incompatible or if required components are not specified or available.
  Fix: Refer to CMake's `FindBoost` documentation and ensure your `CMakeLists.txt` correctly specifies Boost versions and components. `cmeel` automatically sets `CMAKE_PREFIX_PATH` to help CMake locate `cmeel-boost` installations. Ensure your build environment has a compatible C++ toolchain for the Boost version provided.

Install

• pip install cmeel-boost Install latest version

Imports

• Boost C++ Headers/Libraries

  #include <boost/...

  cmeel-boost provides the Boost C++ libraries for use in C++ source files within a project built with cmeel. It does NOT provide Python symbols for direct import into Python code to expose Boost functionality. The 'import' is typically a C++ `#include` in your C++ source code.

Quickstart

cmeel-boost is designed to be a build dependency for other Python packages that wrap C++ code requiring Boost. The quickstart illustrates how a `pyproject.toml` declares `cmeel-boost` as a build-system requirement. Subsequently, a `CMakeLists.txt` within the C++ portion of the project can locate and link against Boost components provided by `cmeel-boost` using standard CMake `find_package` commands. The actual C++ code would then include Boost headers and use its functionalities. The `cmeel` backend automatically sets `CMAKE_PREFIX_PATH` to enable CMake to find installed `cmeel` packages like `cmeel-boost`.

# Assume a C++ project 'my_cpp_lib' that uses Boost.
#
# 1. pyproject.toml for a Python package that depends on my_cpp_lib
#    and needs cmeel-boost as a build dependency:
#
# [build-system]
# requires = ["cmeel[build]", "cmeel-boost~=1.89.0"]
# build-backend = "cmeel.build"
#
# [project]
# name = "my-python-package"
# version = "0.1.0"
#
# 2. CMakeLists.txt for my_cpp_lib (e.g., in a 'src' subdirectory):
#
# cmake_minimum_required(VERSION 3.15)
# project(my_cpp_lib LANGUAGES CXX)
#
# # Find Boost components. cmeel-boost will have installed Boost
# # in a location discoverable by CMake through CMAKE_PREFIX_PATH set by cmeel.
# find_package(Boost 1.89.0 REQUIRED COMPONENTS system thread)
#
# add_library(my_cpp_lib SHARED my_cpp_lib.cpp)
# target_include_directories(my_cpp_lib PUBLIC ${Boost_INCLUDE_DIRS})
# target_link_libraries(my_cpp_lib PUBLIC Boost::system Boost::thread)
#
# 3. my_cpp_lib.cpp (example C++ file using Boost):
#
# #include <iostream>
# #include <boost/version.hpp>
# #include <boost/system/error_code.hpp>
#
# extern "C" void say_boost_version() {
#    std::cout << "Boost Version: " << BOOST_VERSION / 100000 << ".";
#    std::cout << (BOOST_VERSION / 100 % 1000) << ".";
#    std::cout << (BOOST_VERSION % 100) << std::endl;
#    boost::system::error_code ec;
#    // Example use, not doing anything meaningful with ec here
#    if (ec) {
#        std::cerr << "Error: " << ec.message() << std::endl;
#    }
# }
#
# 4. To build a wheel for 'my-python-package':
#    (Ensure your environment has a C++ compiler compatible with Boost.)
#    python -m pip wheel .

# Note: This code block demonstrates the C++/CMake usage. The `python -m cmeel cmake` command 
# is typically run internally by `pip` when building a `cmeel`-based package that depends on `cmeel-boost`.
# For debugging or manual usage in a C++ project outside `cmeel`, you might run:
# export CMAKE_PREFIX_PATH=$(python -m cmeel cmake)
# cmake -S . -B build
# cmake --build build

import os

# Placeholder for a Python script that might invoke the C++ library (if bindings existed)
# cmeel-boost itself does not provide Python callable functions.
print("cmeel-boost provides C++ libraries, not direct Python imports for Boost functionality.")
print("To use it, your Python package must be built with cmeel and link against Boost in its CMake project.")