New jit API entrypoint: gcc_jit_context_compile_to_file

gcc/jit/ChangeLog:
	* docs/cp/topics/results.rst: Rename to...
	* docs/cp/topics/compilation.rst: ...this, and add section on
	ahead-of-time compilation.
	* docs/cp/topics/index.rst: Update for renaming of results.rst
	to compilation.rst.
	* docs/examples/emit-alphabet.bf: New file, a sample "brainf"
	script.
	* docs/examples/tut05-bf.c: New file, implementing a compiler
	for "brainf".
	* docs/internals/test-hello-world.exe.log.txt: Update to reflect
	changes to logger output.
	* docs/intro/index.rst: Add tutorial05.rst
	* docs/intro/tutorial05.rst: New file.
	* docs/topics/results.rst: Rename to...
	* docs/topics/compilation.rst: ...this, and add section on
	ahead-of-time compilation.
	* docs/topics/index.rst: Update for renaming of results.rst to
	compilation.rst.
	* jit-playback.c (gcc::jit::playback::context::compile): Convert
	return type from result * to void.  Move the code to convert to
	dso and dlopen the result to a new pure virtual "postprocess"
	method.
	(gcc::jit::playback::compile_to_memory::compile_to_memory): New
	function.
	(gcc::jit::playback::compile_to_memory::postprocess): New
	function, based on playback::context::compile.
	(gcc::jit::playback::compile_to_file::compile_to_file): New
	function.
	(gcc::jit::playback::compile_to_file::postprocess): New function.
	(gcc::jit::playback::compile_to_file::copy_file): New function.
	(gcc::jit::playback::context::convert_to_dso): Move internals
	to...
	(gcc::jit::playback::context::invoke_driver): New method.  Add
	"-shared" and "-c" options to driver's argv as needed.
	* jit-playback.h: Include "timevar.h".
	(gcc::jit::playback::context::compile): Convert return type from
	result * to void.
	(gcc::jit::playback::context::postprocess): New pure virtual
	function, making this an abstract base class.
	(gcc::jit::playback::context::get_tempdir): New accessor.
	(gcc::jit::playback::context::invoke_driver): New function.
	(class gcc::jit::playback::compile_to_memory): New subclass of
	playback::context.
	(class gcc::jit::playback::compile_to_file): Likewise.
	* jit-recording.c (gcc::jit::recording::context::compile): Use a
	playback::compile_to_memory, and extract its result.
	(gcc::jit::recording::context::compile_to_file): New function.
	* jit-recording.h (gcc::jit::recording::context::compile_to_file):
	New function.
	* libgccjit++.h (gccjit::context::compile_to_file): New method.
	* libgccjit.c (gcc_jit_context_compile): Update log message to
	clarify that this is an in-memory compile.
	(gcc_jit_context_compile_to_file): New function.
	* libgccjit.h (gcc_jit_context): Clarify that you can compile
	a context more than once, and that you can compile to a file
	as well as to memory.
	(gcc_jit_result): Clarify that this is the result of an
	in-memory compilation.
	(gcc_jit_context_compile): Clarify that you can compile, and that
	this is an in-memory compilation.
	(enum gcc_jit_output_kind): New enum.
	(gcc_jit_context_compile_to_file): New function.
	(gcc_jit_context_enable_dump): Clarify comment to cover both forms
	of compilation.
	* libgccjit.map (gcc_jit_context_compile_to_file): New API
	entrypoint.
	* notes.txt: Update to show the playback::context::postprocess
	virtual function.

gcc/testsuite/ChangeLog:
	* jit.dg/harness.h: Include <unistd.h>.
	(CHECK_NO_ERRORS): New.
	(verify_code): Wrap prototype in #ifndef TEST_COMPILING_TO_FILE.
	(test_jit): Support new macro TEST_COMPILING_TO_FILE for exercising
	gcc_jit_context_compile_to_file.
	* jit.dg/jit.exp (fixed_host_execute): Fix the code for passing on
	args to the spawned executable.
	(jit-expand-vars): New function.
	(jit-exe-params): New variable.
	(dg-jit-set-exe-params): New function.
	(jit-dg-test): Detect testcases that use
	jit-verify-compile-to-file and call jit-setup-compile-to-file.
	Set arguments of spawned process to jit-exe-params.
	(jit-get-output-filename): New function.
	(jit-setup-compile-to-file): New function.
	(jit-verify-compile-to-file): New function.
	(jit-run-executable): New function.
	(jit-verify-executable): New function.
	* jit.dg/test-compile-to-assembler.c: New testcase.
	* jit.dg/test-compile-to-dynamic-library.c: New testcase.
	* jit.dg/test-compile-to-executable.c: New testcase.
	* jit.dg/test-compile-to-object.c: New testcase.

From-SVN: r219876

3 files changed, 59 insertions, 49 deletions

diff --git a/gcc/jit/docs/cp/topics/compilation.rst b/gcc/jit/docs/cp/topics/compilation.rst
new file mode 100644
index 0000000..05917e8
--- /dev/null
+++ b/gcc/jit/docs/cp/topics/compilation.rst
@@ -0,0 +1,58 @@
+.. Copyright (C) 2014-2015 Free Software Foundation, Inc.
+   Originally contributed by David Malcolm <dmalcolm@redhat.com>
+
+   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/>.
+
+.. default-domain:: cpp
+
+Compiling a context
+===================
+
+Once populated, a :class:`gccjit::context` can be compiled to
+machine code, either in-memory via :func:`gccjit::context::compile` or
+to disk via :func:`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
+*********************
+
+.. function:: gcc_jit_result *\
+              gccjit::context::compile ()
+
+   This calls into GCC and builds the code, returning a
+   `gcc_jit_result *`.
+
+   This is a thin wrapper around the
+   :c:func:`gcc_jit_context_compile` API entrypoint.
+
+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 :func:`gccjit::context::compile_to_file` method.
+
+.. function:: void \
+              gccjit::context::compile_to_file (enum gcc_jit_output_kind,\
+                                                const char *output_path)
+
+   Compile the :class:`gccjit::context` to a file of the given
+   kind.
+
+   This is a thin wrapper around the
+   :c:func:`gcc_jit_context_compile_to_file` API entrypoint.
diff --git a/gcc/jit/docs/cp/topics/index.rst b/gcc/jit/docs/cp/topics/index.rst
index d47f583..4ebb623 100644
--- a/gcc/jit/docs/cp/topics/index.rst
+++ b/gcc/jit/docs/cp/topics/index.rst
@@ -27,4 +27,4 @@ Topic Reference
    expressions.rst
    functions.rst
    locations.rst
-   results.rst
+   compilation.rst
diff --git a/gcc/jit/docs/cp/topics/results.rst b/gcc/jit/docs/cp/topics/results.rst
deleted file mode 100644
index a48339a..0000000
--- a/gcc/jit/docs/cp/topics/results.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-.. Copyright (C) 2014-2015 Free Software Foundation, Inc.
-   Originally contributed by David Malcolm <dmalcolm@redhat.com>
-
-   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/>.
-
-.. default-domain:: cpp
-
-Compilation results
-===================
-
-.. type:: gcc_jit_result
-
-  A `gcc_jit_result` encapsulates the result of compiling a context.
-
-.. function:: gcc_jit_result *\
-              gccjit::context::compile ()
-
-   This calls into GCC and builds the code, returning a
-   `gcc_jit_result *`.
-
-
-.. function:: void *\
-              gcc_jit_result_get_code (gcc_jit_result *result,\
-                                       const char *funcname)
-
-   Locate a given function within the built machine code.
-   This will need to be cast to a function pointer of the
-   correct type before it can be called.
-
-
-.. function:: void\
-              gcc_jit_result_release (gcc_jit_result *result)
-
-   Once we're done with the code, this unloads the built .so file.
-   This cleans up the result; after calling this, it's no longer
-   valid to use the result.