More recipe doc

inclement · inclement · commit 03c676a5fa93 · 2015-06-28T16:05:29.000+01:00
diff --git a/doc/source/recipes.rst b/doc/source/recipes.rst
@@ -84,10 +84,165 @@ though may need to use the arch name ``arch.arch``.
 .. note:: You can also implement arch-specific versions of each
           method, which are called (if they exist) by the superclass,
           e.g. ``def prebuild_armeabi(self, arch)``.
+          
 
+This is the core of what's necessary to write a recipe, but has not
+covered any of the details of how one actually writes code to compile
+for android. This is covered in the next sections, including the
+`standard mechanisms <standard_mechanisms_>`_ used as part of the
+build, and the details of specific recipe classes for Python, Cython,
+and some generic compiled recipes. If your module is one of the
+latter, you should use these later classes rather than reimplementing
+the functionality from scratch.
 
-.. _recipe_class:
+.. _standard_mechanisms:
+
+Methods and tools to help with compilation
+------------------------------------------
+
+Patching modules before installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can easily apply patches to your recipes with the ``apply_patch``
+method. For instance, you could do this in your prebuild method::
+
+  import sh
+  def prebuild_arch(self, arch):
+       super(YourRecipe, self).prebuild_arch(arch)
+       build_dir = self.get_build_dir(arch.arch)
+       if exists(join(build_dir, '.patched')):
+           print('Your recipe is already patched, skipping')
+           return
+       self.apply_patch('some_patch.patch')
+       shprint(sh.touch, join(build_dir, '.patched'))
+
+The path to the patch should be in relation to your recipe code.
+In this case, ``some_path.patch`` must be in the same directory as the
+recipe.
+
+This code also manually takes care to patch only once. You can use the
+same strategy yourself, though a more generic solution may be provided
+in the future.
+
+Compiling for the Android architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When performing any compilation, it is vital to do so with appropriate
+environment variables set, ensuring that the Android libraries are
+properly linked and the compilation target is the correct
+architecture.
+
+You can get a dictionary of appropriate environment variables with the
+``get_recipe_env`` method. You should make sure to set this
+environment for any processes that you call. It is convenient to do
+this using the ``sh`` module as follows::
+
+  def build_arch(self, arch):
+      super(YourRecipe, self).build_arch(arch)
+      env = self.get_recipe_env(arch)
+      sh.echo('$PATH', _env=env)  # Will print the PATH entry fron the
+                                  # env dict
+
+You can also use the ``shprint`` helper function from the p4a
+toolchain module, which will print information about the process and
+its current status::
+
+  from toolchain import shprint
+  shprint(sh.echo, '$PATH', _env=env)
+
+You can also override the ``get_recipe_env`` method to add new env
+vars for the use of your recipe. For instance, the Kivy recipe does
+the following when compiling for SDL2, in order to tell Kivy what
+backend to use::
+
+    def get_recipe_env(self, arch):
+        env = super(KivySDL2Recipe, self).get_recipe_env(arch)
+        env['USE_SDL2'] = '1'
+
+        env['KIVY_SDL2_PATH'] = ':'.join([
+            join(self.ctx.bootstrap.build_dir, 'jni', 'SDL', 'include'),
+            join(self.ctx.bootstrap.build_dir, 'jni', 'SDL2_image'),
+            join(self.ctx.bootstrap.build_dir, 'jni', 'SDL2_mixer'),
+            join(self.ctx.bootstrap.build_dir, 'jni', 'SDL2_ttf'),
+            ])
+        return env
+  
+.. warning:: When using the sh module like this the new env *completely
+          replaces* the normal environment, so you must define any env
+          vars you want to access.
+          
+Including files with your recipe
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The should_build method
+~~~~~~~~~~~~~~~~~~~~~~~
+          
+
+Using a PythonRecipe
+--------------------
+
+If your recipe is to install a Python module without compiled
+components, you should use a PythonRecipe. This overrides
+``build_arch`` to automatically call the normal ``python setup.py
+install`` with an appropriate environment.
+
+For instance, the following is all that's necessary to create a recipe
+for the Vispy module::
+
+  from toolchain import PythonRecipe
+  class VispyRecipe(PythonRecipe):
+      version = 'master'
+      url = 'https://github.com/vispy/vispy/archive/{version}.zip'
+
+      depends = ['python2', 'numpy']
+      
+      site_packages_name = 'vispy'
+
+  recipe = VispyRecipe()
+  
+The ``site_packages_name`` is a new attribute that identifies the
+folder in which the module will be installed in the Python
+package. This is only essential to add if the name is different to the
+recipe name. It is used to check if the recipe installation can be
+skipped, which is the case if the folder is already present in the
+Python installation.
+  
+For reference, the code that accomplishes this is the following::
+
+    def build_arch(self, arch):
+        super(PythonRecipe, self).build_arch(arch)
+        self.install_python_package()
 
+    def install_python_package(self):
+        '''Automate the installation of a Python package (or a cython
+        package where the cython components are pre-built).'''
+        arch = self.filtered_archs[0]
+        env = self.get_recipe_env(arch)
+
+        info('Installing {} into site-packages'.format(self.name))
+
+        with current_directory(self.get_build_dir(arch.arch)):
+            hostpython = sh.Command(self.ctx.hostpython)
+
+            shprint(hostpython, 'setup.py', 'install', '-O2', _env=env)
+            
+This combines techniques and tools from the above documentation to
+create a generic mechanism for all Python modules.
+
+.. note:: The hostpython is the path to the Python binary that should
+          be used for any kind of installation. You *must* run Python
+          in a similar way if you need to do so in any of your own
+          recipes.
+
+
+Using a CythonRecipe
+--------------------
+
+Using a CompiledComponentsPythonRecipe
+--------------------------------------
+
+
+.. _recipe_class:
 
 The ``Recipe`` class
 --------------------
