More recipe documentation

inclement · inclement · commit dd5417d5cc2d · 2015-06-28T16:18:10.000+01:00
diff --git a/doc/source/recipes.rst b/doc/source/recipes.rst
@@ -238,9 +238,74 @@ create a generic mechanism for all Python modules.
 Using a CythonRecipe
 --------------------
 
+If your recipe is to install a Python module that uses Cython, you
+should use a CythonRecipe. This overrides ``build_arch`` to both build
+the cython components and to install the Python module just like a
+normal PythonRecipe.
+
+For instance, the following is all that's necessary to make a recipe
+for Kivy (in this case, depending on Pygame rather than SDL2)::
+
+  class KivyRecipe(CythonRecipe):
+       version = 'stable'
+       url = 'https://github.com/kivy/kivy/archive/{version}.zip'
+       name = 'kivy'
+
+       depends = ['pygame', 'pyjnius', 'android']
+
+  recipe = KivyRecipe()
+  
+For reference, the code that accomplishes this is the following::
+
+    def build_arch(self, arch):
+        Recipe.build_arch(self, arch)  # a hack to avoid calling
+                                       # PythonRecipe.build_arch
+        self.build_cython_components(arch)
+        self.install_python_package()  # this is the same as in a PythonRecipe
+
+    def build_cython_components(self, arch):
+        env = self.get_recipe_env(arch)
+        with current_directory(self.get_build_dir(arch.arch)):
+            hostpython = sh.Command(self.ctx.hostpython)
+            
+            # This first attempt *will* fail, because cython isn't
+            # installed in the hostpython
+            try:
+                shprint(hostpython, 'setup.py', 'build_ext', _env=env)
+            except sh.ErrorReturnCode_1:
+                pass
+
+            # ...so we manually run cython from the user's system
+            shprint(sh.find, self.get_build_dir('armeabi'), '-iname', '*.pyx', '-exec',
+                    self.ctx.cython, '{}', ';', _env=env)
+
+            # now cython has already been run so the build works
+            shprint(hostpython, 'setup.py', 'build_ext', '-v', _env=env)
+
+            # stripping debug symbols lowers the file size a lot
+            build_lib = glob.glob('./build/lib*')
+            shprint(sh.find, build_lib[0], '-name', '*.o', '-exec',
+                    env['STRIP'], '{}', ';', _env=env)
+
+The failing build and manual cythonisation is necessary, first to
+make sure that any .pyx files have been generated by setup.py, and
+second because cython isn't installed in the hostpython build.
+ 
+Other than this, these methods follow the techniques in the above
+documentation to make a generic recipe for most cython based modules.
+
 Using a CompiledComponentsPythonRecipe
 --------------------------------------
 
+This is similar to a CythonRecipe but is intended for modules like
+numpy which include compiled but non-cython components. It uses a
+similar mechanism to compile with the right environment.
+
+This isn't documented yet because it will probably be changed so that
+CythonRecipe inherits from it (to avoid code duplication).
+
+Using an NDKRecipe
+------------------
 
 .. _recipe_class:
 
