Metadata-Version: 2.4
Name: cmake-pip
Version: 0.1
Summary: Distributing CMake projects with distutils/setuptools/pip
Author-email: Raffi Enficiaud <raffi.enficiaud@free.fr>
Maintainer-email: Raffi Enficiaud <raffi.enficiaud@free.fr>
License: Boost Software License - Version 1.0 - August 17th, 2003
Project-URL: homepage, https://bitbucket.org/renficiaud/cmake-pip/
Project-URL: Documentation, https://cmake-pip.readthedocs.io/en/latest/
Project-URL: repository, https://bitbucket.org/renficiaud/cmake-pip/
Keywords: cmake,conan,C,C++,builb,distutils,setuptools,pip,packaging,cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: setuptools
Requires-Dist: importlib_resources; python_version < "3.10"
Requires-Dist: patchelf; sys_platform == "linux"
Provides-Extra: conan
Requires-Dist: conan>=2.0; extra == "conan"
Dynamic: license-file

# cmake-pip

**CMake bindings to pip made simple.**

This project makes easy the creation and distribution of python packages with
extensions built with [CMake](http://www.cmake.org) and with complex set of dependencies through its 
integration with [`conan`](https://conan.io/).

# Why using `cmake-pip`
Python extension system through `setuptools` is simple and effective, but hardly scales up
beyond a few source files, and does not handle dependencies that are outside the `python` ecosystem
well: linking the python extension to eg. a system library makes the packaging less 
portable and harder to maintain.

CMake is a mature tool for defining C/C++ projects with more than 2 decades of 
updates and running,
it is widely accepted as an industry standard for building simple or complex projects, in a platform
agnostic way. It provides a wide spectrum of features and integration with libraries and compilers.

Your own C/C++ library is just one side of the story: a common case is when a project needs 
to integrate with features provided by libraries that are external to your project. CMake usually
integrates well with this, but performs not so well when several projects, each with their own build
infrastructure, variables, options... are involved. And this is where `conan` shines:
its simplicity for injecting external projects to yours and its great community support
provides you the missing piece in the C/C++ world for constructing software with complex
dependencies.


# Documentation
The full documentation of `cmake-pip` is available
[online](https://cmake-pip.readthedocs.io/en/feat-pyproject/) — start with the
worked examples, each of which is a fixture of the test suite and installs
end-to-end.

# Features

* one declaration in `setup.py`, plain modern CMake on the project side
* wheels, source distributions and PEP 660 editable installs
* version injection into the cmake configuration (`setuptools_scm` friendly)
* relocatable packages: `rpath` rewriting, runtime dependency collection, and
  linux `soname` mangling of the vendored libraries
* conan integration: dependencies declared in `setup.py`, recipes pulled from
  `conan-center-index` at a pinned revision, self-provisioned `CONAN_HOME`
* build only what the wheel needs (the `cmake_pip_target` umbrella target) and
  optionally run the project's `ctest` suite before anything is staged

# How to use

The interface is made very simple:

1. on the `setup.py`/`pyproject.toml` side, use a specific extension to instruct the python 
   packaging system about CMake and conan dependencies.

   For your `pyproject.toml`, you just need to specify a build dependency:

   ```toml
   [build-system]
      requires = ["setuptools", "cmake-pip"]
   ```

   On the `setup.py`, declare your CMake project and instruct `setuptools` as follow:
   ```python
   # setup.py -- everything else lives in pyproject.toml
   from setuptools import setup
   from cmake_pip.cmake_extension import ExtensionCMake
  
   my_cmake_extensions = ExtensionCMake(
    "my_package.my_extensions",
    "my_cmake_project/CMakeLists.txt",
    cmake_install_component="python_ext_component")

   setup(ext_modules=[my_cmake_extensions])
   ```

1. on the cmake side: use directives to declare the content of a python package, 

    ```cmake
    # this declares "python_package_add_target" and is provided
    # by cmake-pip
    find_package(cmakepip)

    python3_add_library(my_module1 MODULE
        src/my_module1.cpp)
    python3_add_library(my_module2 MODULE
        src/my_module2.cpp)

    python_package_add_target(TARGET my_module1
                              DESTINATION my_extensions/
                              PYTHON_PACKAGE python_ext_component)
    python_package_add_target(TARGET my_module2
                              DESTINATION my_extensions/
                              PYTHON_PACKAGE python_ext_component)
    ```

Et voilà! With very little changes to your CMake and python package side, you
can define a python package with many python extensions. No need to specify those
in the python package, `cmake-pip` takes care of it. No need also to package the shared libraries
your extensions depend on, neither complicated renaming: `cmake-pip` is there for this.
