Merge pull request #96 from lazka/get-include

Move header into the package and add a get_include() function

.appveyor.yml

@@ -1,5 +1,17 @@
 environment:
   matrix:
+    - MSYS2_ARCH: x86_64
+      MSYSTEM: MINGW64
+      PYTHON: python2
+    - MSYS2_ARCH: i686
+      MSYSTEM: MINGW32
+      PYTHON: python2
+    - MSYS2_ARCH: x86_64
+      MSYSTEM: MINGW64
+      PYTHON: python3
+    - MSYS2_ARCH: i686
+      MSYSTEM: MINGW32
+      PYTHON: python3
     - MSVC_PLATFORM: x86
       PYTHON_ROOT: Python27
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2013
@@ -18,24 +30,12 @@ environment:
     - MSVC_PLATFORM: x64
       PYTHON_ROOT: Python36-x64
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-    - MSYS2_ARCH: x86_64
-      MSYSTEM: MINGW64
-      PYTHON: python2
-    - MSYS2_ARCH: i686
-      MSYSTEM: MINGW32
-      PYTHON: python2
-    - MSYS2_ARCH: x86_64
-      MSYSTEM: MINGW64
-      PYTHON: python3
-    - MSYS2_ARCH: i686
-      MSYSTEM: MINGW32
-      PYTHON: python3
 
 build_script:
   - IF DEFINED MSYSTEM set PATH=C:\msys64\%MSYSTEM%\bin;C:\msys64\usr\bin;%PATH%
   - IF DEFINED MSYSTEM set CHERE_INVOKING=yes
-  - IF DEFINED MSYSTEM bash -lc "bash .appveyor/msys2-pre.sh"
-  - IF DEFINED MSYSTEM bash -lc "bash .appveyor/msys2.sh"
+  - IF DEFINED MSYSTEM bash -lc "bash -x .appveyor/msys2-pre.sh"
+  - IF DEFINED MSYSTEM bash -lc "bash -x .appveyor/msys2.sh"
   - IF DEFINED MSVC_PLATFORM ".appveyor/msvc.bat"
 
 deploy: off

.appveyor/msys2.sh

@@ -10,6 +10,7 @@ export CFLAGS="-std=c90 -Wall -Wno-long-long -Werror -coverage"
 $PYTHON -m coverage run --branch setup.py test
 $PYTHON -m codecov
 $PYTHON setup.py sdist
+$PYTHON setup.py install --root="$(pwd)"/_root_abs
 $PYTHON -m pip install dist/*
 
 # Also test with older cairo

.travis.yml

@@ -67,5 +67,12 @@ script:
   - python -m codecov
   - python -m flake8 .
   - python setup.py sdist
-  - if [[ "$TRAVIS_PYTHON_VERSION" != "pypy" ]] && [[ "$TRAVIS_PYTHON_VERSION" != "pypy3" ]]; then python -m pip install "$(eval 'echo dist/*')"; fi
+  - python setup.py bdist
+  - python setup.py install --root=_root
+  - python setup.py install --root="$(pwd)"/_root_abs
+  - python setup.py install --user
+  - PYCAIRO_SETUPTOOLS=1 python setup.py bdist_egg
+  - PYCAIRO_SETUPTOOLS=1 python setup.py bdist_wheel
+  - PYCAIRO_SETUPTOOLS=1 python setup.py install --root=_root_setup
+  - if [[ "$TRAVIS_PYTHON_VERSION" != "pypy" ]] && [[ "$TRAVIS_PYTHON_VERSION" != "pypy3" ]]; then python -m pip install .; fi
   - if [[ "$TRAVIS_PYTHON_VERSION" != "3.3" ]]; then python -m sphinx -W -a -E -b html -n docs docs/_build; fi

cairo/__init__.py

@@ -1 +1,25 @@
 from ._cairo import *  # noqa: F401,F403
+
+
+def get_include():
+    """Returns a path to the directory containing the C header files"""
+
+    import os
+
+    def is_ok(path):
+        return os.path.exists(path) and os.path.isdir(path)
+
+    package_path = os.path.dirname(os.path.realpath(__file__))
+    install_path = os.path.join(package_path, "include")
+
+    # in case we are installed
+    if is_ok(install_path):
+        return install_path
+
+    # in case we are running from source
+    if is_ok(package_path):
+        return package_path
+
+    # in case we are in an .egg
+    import pkg_resources
+    return pkg_resources.resource_filename(__name__, "include")

docs/pycairo_c_api.rst

@@ -11,6 +11,41 @@ This manual documents the API used by C and C++ programmers who want to write
 extension modules that use pycairo.
 
 
+Pycairo Compiler Flags
+======================
+
+To compile a Python extension using Pycairo you need to know where Pycairo and
+cairo are located and what flags to pass to the compiler and linker.
+
+1. Variant:
+
+    Only available since version 1.15.7.
+
+    While Pycairo installs a pkg-config file, in case of virtualenvs,
+    installation to the user directory or when using wheels/eggs, pkg-config
+    will not be able to locate the .pc file. The :func:`get_include` function
+    should work in all cases, as long as Pycairo is in your Python search path.
+
+    Compiler Flags:
+        * ``python -c "import cairo; print(cairo.get_include())"``
+        * ``pkg-config --cflags cairo``
+
+    Linker Flags:
+        * ``pkg-config --libs cairo``
+
+2. Variant:
+
+    This works with older versions, but with the limitations mentioned above.
+    Use it as a fallback if you want to support older versions or if your
+    module does not require virtualenv/pip support.
+
+    Compiler Flags:
+        * ``pkg-config --cflags pycairo`` or ``pkg-config --cflags py3cairo``
+
+    Linker Flags:
+        * ``pkg-config --libs pycairo`` or ``pkg-config --libs py3cairo``
+
+
 .. _api-includes:
 
 To access the Pycairo C API under Python 2
@@ -21,7 +56,7 @@ Edit the client module file to add the following lines::
   /* All function, type and macro definitions needed to use the Pycairo/C API
    * are included in your code by the following line
    */
-  #include "Pycairo.h"
+  #include "pycairo.h"
 
   /* define a variable for the C API */
   static Pycairo_CAPI_t *Pycairo_CAPI;
@@ -52,21 +87,6 @@ Example showing how to import the pycairo API::
   }
 
 
-Pkg-Config Setup
-================
-
-pycairo installs "pycairo.pc" or "py3cairo.pc" in case of a Python 3 install:
-
-.. code-block:: console
-
-    > pkg-config --libs --cflags pycairo
-    > pkg-config --libs --cflags py3cairo
-    -I/usr/include/cairo -I/usr/include/glib-2.0
-    -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1
-    -I/usr/include/freetype2 -I/usr/include/libpng16 -I/usr/include/pycairo
-    -lcairo
-
-
 Misc Functions
 ==============
 

docs/reference/constants.rst

@@ -26,6 +26,15 @@ Module Functions
    Returns the version of the underlying C cairo library as a human-readable
    string of the form "X.Y.Z".
 
+.. function:: get_include()
+
+    :returns: a path to the directory containing the C header files
+    :rtype: str
+
+    Gives the include path which should be passed to the compiler.
+
+    .. versionadded:: 1.15.7
+
 
 Module Constants
 ================