Rewrite docs about gccjit.Result

doc/compilation.rst

@@ -0,0 +1,132 @@
+.. Copyright 2014-2015 David Malcolm <dmalcolm@redhat.com>
+   Copyright 2014-2015 Red Hat, Inc.
+
+   This is free software: you can redistribute it and/or modify it
+   under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see
+   <http://www.gnu.org/licenses/>.
+
+Compiling a context
+===================
+
+Once populated, a :py:class:`gccjit.Context` can be compiled to
+machine code, either in-memory via :py:meth:`gccjit.Context.compile` or
+to disk via :py:meth:`gccjit.Context.compile_to_file`.
+
+You can compile a context multiple times (using either form of
+compilation), although any errors that occur on the context will
+prevent any future compilation of that context.
+
+In-memory compilation
+*********************
+
+.. py:method:: gccjit.Context.compile(self)
+
+       :rtype: :py:class:`gccjit.Result`
+
+   This calls into GCC and builds the code, returning a
+   :py:class:`gccjit.Result`.
+
+.. py:class:: gccjit.Result
+
+   A :py:class:`gccjit.Result` encapsulates the result of compiling a
+   :py:class:`gccjit.Context` in-memory, and the lifetimes of any
+   machine code functions or globals that are within the result.
+
+   .. py:method:: get_code(funcname)
+
+      Locate the given function within the built machine code.
+
+      Functions are looked up by name.  For this to succeed, a function
+      with a name matching `funcname` must have been created on
+      `result`'s context (or a parent context) via a call to
+      :py:meth:`gccjit.Context.new_function` with `kind`
+      :py:data:`gccjit.FunctionKind.EXPORTED`.
+
+      .. error-handling?
+
+      The returned value is an
+      `int`, actually a pointer to the machine code within the
+      address space of the process.  This will need to be wrapped up
+      with `ctypes` to be callable::
+
+         import ctypes
+
+         # "[int] -> int" functype:
+         int_int_func_type = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int)
+         code = int_int_func_type(jit_result.get_code(b"square"))
+         assert code(5) == 25
+
+      The code has the same lifetime as the :py:class:`gccjit.Result`
+      instance; the pointer becomes invalid when the result instance
+      is cleaned up.
+
+.. TODO: gcc_jit_result_get_global
+
+Ahead-of-time compilation
+*************************
+
+Although libgccjit is primarily aimed at just-in-time compilation, it
+can also be used for implementing more traditional ahead-of-time
+compilers, via the :py:meth:`gccjit.Context.compile_to_file`
+API entrypoint.
+
+.. py:method:: gccjit.Context.compile_to_file(self, kind, path)
+
+   Compile the context to a file of the given
+   kind::
+
+     ctxt.compile_to_file(gccjit.OutputKind.EXECUTABLE,
+                          'a.out')
+
+   :py:meth:`gccjit.Context.compile_to_file` ignores the suffix of
+   ``path``, and insteads uses `kind` to decide what to do.
+
+   .. note::
+
+      This is different from the ``gcc`` program, which does make use of the
+      suffix of the output file when determining what to do.
+
+   The available kinds of output are:
+
+   ============================================  ==============
+   Output kind                                     Typical suffix
+   ============================================  ==============
+   :py:data:`gccjit.OutputKind.ASSEMBLER`        .s
+   :py:data:`gccjit.OutputKind.OBJECT_FILE`      .o
+   :py:data:`gccjit.OutputKind.DYNAMIC_LIBRARY`  .so or .dll
+   :py:data:`gccjit.OutputKind.EXECUTABLE`       None, or .exe
+   ============================================  ==============
+
+.. py:class:: gccjit.OutputKind
+
+   .. py:data:: ASSEMBLER
+
+      Compile the context to an assembler file.
+
+   .. py:data:: OBJECT_FILE
+
+      Compile the context to an object file.
+
+   .. py:data:: DYNAMIC_LIBRARY
+
+      Compile the context to a dynamic library.
+
+      There is currently no support for specifying other libraries to link
+      against.
+
+   .. py:data:: EXECUTABLE
+
+      Compile the context to an executable.
+
+      There is currently no support for specifying libraries to link
+      against.

doc/contexts.rst

@@ -74,12 +74,6 @@ Compilation contexts
 
           int_type = ctxt.get_int_type(4, is_signed=True)
 
-    .. py:method:: compile()
-
-       :rtype: :py:class:`gccjit.Result`
-
-    .. py:method:: compile_to_file(kind, path)
-
     .. py:method:: dump_to_file(path, update_locations)
 
     .. py:method:: get_first_error()

doc/index.rst

@@ -31,7 +31,7 @@ Contents:
    expressions.rst
    functions.rst
    locations.rst
-   results.rst
+   compilation.rst
 
 This document describes the
 `Python bindings <https://github.com/davidmalcolm/pygccjit>`_