6 files changed, 90 insertions, 31 deletions
diff --git a/docs/examples/userguide/external_C_code/delorean.pyx b/docs/examples/userguide/external_C_code/delorean.pyx
index 52c713616..9c6af9f87 100644
--- a/docs/examples/userguide/external_C_code/delorean.pyx
+++ b/docs/examples/userguide/external_C_code/delorean.pyx
@@ -1,9 +1,9 @@
-# delorean.pyx
-
-cdef public struct Vehicle:
-    int speed
-    float power
-
-cdef api void activate(Vehicle *v):
-    if v.speed >= 88 and v.power >= 1.21:
-        print("Time travel achieved")
-\ No newline at end of file
+# delorean.pyx
+
+cdef public struct Vehicle:
+    int speed
+    float power
+
+cdef api void activate(Vehicle *v) except *:
+    if v.speed >= 88 and v.power >= 1.21:
+        print("Time travel achieved")
diff --git a/docs/examples/userguide/external_C_code/marty.c b/docs/examples/userguide/external_C_code/marty.c
index 8096ab19a..d7f5117f7 100644
--- a/docs/examples/userguide/external_C_code/marty.c
+++ b/docs/examples/userguide/external_C_code/marty.c
@@ -1,13 +1,14 @@
-# marty.c
-#include "delorean_api.h"
-
-Vehicle car;
-
-int main(int argc, char *argv[]) {
-	Py_Initialize();
-	import_delorean();
-	car.speed = atoi(argv[1]);
-	car.power = atof(argv[2]);
-	activate(&car);
-	Py_Finalize();
-}
+# marty.c
+#include "delorean_api.h"
+
+Vehicle car;
+
+int main(int argc, char *argv[]) {
+	Py_Initialize();
+	import_delorean();
+	car.speed = atoi(argv[1]);
+	car.power = atof(argv[2]);
+	activate(&car);
+	/* Error handling left out - call PyErr_Occurred() to test for Python exceptions. */
+	Py_Finalize();
+}
diff --git a/docs/examples/userguide/external_C_code/platform_adaptation.pyx b/docs/examples/userguide/external_C_code/platform_adaptation.pyx
new file mode 100644
index 000000000..0beece8f4
--- /dev/null
+++ b/docs/examples/userguide/external_C_code/platform_adaptation.pyx
@@ -0,0 +1,14 @@
+cdef extern from *:
+    """
+    #if defined(_WIN32) || defined(MS_WINDOWS) || defined(_MSC_VER)
+      #include "stdlib.h"
+      #define myapp_sleep(m)  _sleep(m)
+    #else
+      #include <unistd.h>
+      #define myapp_sleep(m)  ((void) usleep((m) * 1000))
+    #endif
+    """
+    # using "myapp_" prefix in the C code to prevent C naming conflicts
+    void msleep "myapp_sleep"(int milliseconds) nogil
+
+msleep(milliseconds=1)
diff --git a/docs/examples/userguide/external_C_code/struct_field_adaptation.h b/docs/examples/userguide/external_C_code/struct_field_adaptation.h
new file mode 100644
index 000000000..ca55460f4
--- /dev/null
+++ b/docs/examples/userguide/external_C_code/struct_field_adaptation.h
@@ -0,0 +1,13 @@
+typedef struct {
+    int field1;
+    int field2;
+    int newly_added_field;
+} StructType;
+
+static StructType global_struct;
+
+static StructType *get_struct_ptr() {
+    return &global_struct;
+}
+
+#define C_LIB_VERSION 20
diff --git a/docs/examples/userguide/external_C_code/struct_field_adaptation.pyx b/docs/examples/userguide/external_C_code/struct_field_adaptation.pyx
new file mode 100644
index 000000000..cff6bbdc2
--- /dev/null
+++ b/docs/examples/userguide/external_C_code/struct_field_adaptation.pyx
@@ -0,0 +1,31 @@
+cdef extern from "struct_field_adaptation.h":
+    """
+    #define HAS_NEWLY_ADDED_FIELD  (C_LIB_VERSION >= 20)
+
+    #if HAS_NEWLY_ADDED_FIELD
+        #define _mylib_get_newly_added_field(a_struct_ptr)  ((a_struct_ptr)->newly_added_field)
+        #define _mylib_set_newly_added_field(a_struct_ptr, value)  ((a_struct_ptr)->newly_added_field) = (value)
+    #else
+        #define _mylib_get_newly_added_field(a_struct_ptr)  (0)
+        #define _mylib_set_newly_added_field(a_struct_ptr, value)  ((void) (value))
+    #endif
+    """
+
+    # Normal declarations provided by the C header file:
+    ctypedef struct StructType:
+        int field1
+        int field2
+
+    StructType *get_struct_ptr()
+
+    # Special declarations conditionally provided above:
+    bint HAS_NEWLY_ADDED_FIELD
+    int get_newly_added_field "_mylib_get_newly_added_field" (StructType *struct_ptr)
+    void set_newly_added_field "_mylib_set_newly_added_field" (StructType *struct_ptr, int value)
+
+
+cdef StructType *some_struct_ptr = get_struct_ptr()
+
+print(some_struct_ptr.field1)
+if HAS_NEWLY_ADDED_FIELD:
+    print(get_newly_added_field(some_struct_ptr))
diff --git a/docs/examples/userguide/external_C_code/c_code_docstring.pyx b/docs/examples/userguide/external_C_code/verbatim_c_code.pyx
index 430e89c48..fb1937166 100644
--- a/docs/examples/userguide/external_C_code/c_code_docstring.pyx
+++ b/docs/examples/userguide/external_C_code/verbatim_c_code.pyx
@@ -1,9 +1,9 @@
-cdef extern from *:
-    """
-    /* This is C code which will be put
-     * in the .c file output by Cython */
-    static long square(long x) {return x * x;}
-    #define assign(x, y) ((x) = (y))
-    """
-    long square(long x)
-    void assign(long& x, long y)
+cdef extern from *:
+    """
+    /* This is C code which will be put
+     * in the .c file output by Cython */
+    static long square(long x) {return x * x;}
+    #define assign(x, y) ((x) = (y))
+    """
+    long square(long x)
+    void assign(long& x, long y)