JIT: Update docs

JIT: Update docs

[Petter Tomner]

Hi!

I messed up some formatting in the doc rts-files in the constructor commit.

Here is a patch fixing that, adding the ABI key in compability, and also changing
a comment about linking not being possible, that is not true since drive options were
added.

I built the docs to verify it looks nice. The patch only touches docs.

Regards, Petter

From 450c90fce5b6c5a9522345b65a53057d3d7201b3 Mon Sep 17 00:00:00 2001
From: Petter Tomner <tomner@kth.se>
Date: Sat, 19 Feb 2022 16:01:54 +0100
Subject: [PATCH] jit: Update docs

Update docs concerning linking and fix formating errors.

gcc/jit/docs/topics/
	* compatibility.rst: Add 19 tag
	* compilation.rst: Linking
	* contexts.rst: Linking example
	* expressions.rst: Fix formating and dropped 's'

Signed-off-by:
2022-02-19	Petter Tomner	<tomner@kth.se>
---
 gcc/jit/docs/topics/compatibility.rst | 12 ++++++++++++
 gcc/jit/docs/topics/compilation.rst   |  8 ++------
 gcc/jit/docs/topics/contexts.rst      |  5 +++++
 gcc/jit/docs/topics/expressions.rst   | 15 ++++++++++-----
 4 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/gcc/jit/docs/topics/compatibility.rst b/gcc/jit/docs/topics/compatibility.rst
index 16cebe31a10..030e72165b7 100644
--- a/gcc/jit/docs/topics/compatibility.rst
+++ b/gcc/jit/docs/topics/compatibility.rst
@@ -302,3 +302,15 @@ thread-local storage model of a variable:
 section of a variable:
 
   * :func:`gcc_jit_lvalue_set_link_section`
+
+.. _LIBGCCJIT_ABI_19:
+
+``LIBGCCJIT_ABI_19``
+-----------------------
+``LIBGCCJIT_ABI_19`` covers the addition of an API entrypoint to set the link
+section of a variable:
+
+  * :func:`gcc_jit_context_new_array_constructor`
+  * :func:`gcc_jit_context_new_struct_constructor`
+  * :func:`gcc_jit_context_new_union_constructor`
+  * :func:`gcc_jit_global_set_initializer_rvalue`
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index 0f90db3b70e..9b1eed2dede 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -146,6 +146,8 @@ can also be used for implementing more traditional ahead-of-time
 compilers, via the :c:func:`gcc_jit_context_compile_to_file`
 API entrypoint.
 
+For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`.
+
 .. function:: void \
               gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, \
                                                enum gcc_jit_output_kind output_kind,\
@@ -188,12 +190,6 @@ Output kind                                     Typical suffix
 
    Compile the context to a dynamic library.
 
-   There is currently no support for specifying other libraries to link
-   against.
-
 .. c:macro:: GCC_JIT_OUTPUT_KIND_EXECUTABLE
 
    Compile the context to an executable.
-
-   There is currently no support for specifying libraries to link
-   against.
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index 68ab7ab1321..14ee57e2e54 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -569,6 +569,11 @@ Additional command-line options
       gcc_jit_context_add_driver_option (ctxt, "-lm");
       gcc_jit_context_add_driver_option (ctxt, "-fuse-linker-plugin");
 
+      gcc_jit_context_add_driver_option (ctxt, "obj.o");
+
+      gcc_jit_context_add_driver_option (ctxt, "-L.");
+      gcc_jit_context_add_driver_option (ctxt, "-lwhatever");
+
    Note that only some options are likely to be meaningful; there is no
    "frontend" within libgccjit, so typically only those affecting
    assembler and linker are likely to be useful.
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 791a20398ca..9267b6d2ad6 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -152,6 +152,7 @@ Constructor expressions
    their presence using:
 
    .. code-block:: c
+
      #ifdef LIBGCCJIT_HAVE_CTORS
 
 .. function:: gcc_jit_rvalue *\
@@ -186,6 +187,7 @@ Constructor expressions
    presence using:
 
    .. code-block:: c
+
      #ifdef LIBGCCJIT_HAVE_CTORS
 
 .. function:: gcc_jit_rvalue *\
@@ -194,7 +196,7 @@ Constructor expressions
 						      gcc_jit_type *type,\
 						      size_t num_values,\
 						      gcc_jit_field **fields,\
-						      gcc_jit_rvalue **value)
+						      gcc_jit_rvalue **values)
 
 
    Create a constructor for a struct as an rvalue.
@@ -235,6 +237,7 @@ Constructor expressions
    presence using:
 
    .. code-block:: c
+
      #ifdef LIBGCCJIT_HAVE_CTORS
 
 .. function:: gcc_jit_rvalue *\
@@ -265,6 +268,7 @@ Constructor expressions
    presence using:
 
    .. code-block:: c
+
      #ifdef LIBGCCJIT_HAVE_CTORS
 
 Vector expressions
@@ -803,14 +807,14 @@ Global variables
       #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer
 
 .. function:: gcc_jit_lvalue *\
-	      gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global,
+	      gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global,\
 	                                             gcc_jit_rvalue *init_value)
 
    Set the initial value of a global with an rvalue.
 
    The rvalue needs to be a constant expression, e.g. no function calls.
 
-   The global can't have the ``kind`` :ref:`GCC_JIT_GLOBAL_IMPORTED`.
+   The global can't have the ``kind`` :c:macro:`GCC_JIT_GLOBAL_IMPORTED`.
 
    As a non-comprehensive example it is OK to do the equivalent of:
 
@@ -822,8 +826,9 @@ Global variables
        const int baz = 3; /* rvalue from gcc_jit_context_rvalue_from_int.  */
        int boz = baz; /* rvalue from gcc_jit_lvalue_as_rvalue.  */
 
-   Use together with :ref:`gcc_jit_context_new_constructor` to
-   initialize structs, unions and arrays.
+   Use together with :c:func:`gcc_jit_context_new_struct_constructor`,
+   :c:func:`gcc_jit_context_new_union_constructor`, :c:func:`gcc_jit_context_new_array_constructor`
+   to initialize structs, unions and arrays.
 
    On success, returns the ``global`` parameter unchanged. Otherwise, ``NULL``.
 
-- 
2.34.1