From: Petter Tomner <tomner@kth.se>
Date: Sat, 19 Feb 2022 15:34:12 +0000 (+0000)
Subject: jit: Update docs
X-Git-Tag: upstream/12.2.0~739
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=aed0f014781ee334921030d4b86e295bd1080b96;p=platform%2Fupstream%2Fgcc.git

jit: Update docs

Update docs concerning linking and fix formatting errors.

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

Signed-off-by: Petter Tomner	2022-02-19	<tomner@kth.se>
---

diff --git a/gcc/jit/docs/topics/compatibility.rst b/gcc/jit/docs/topics/compatibility.rst
index 16cebe3..03e3f34 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 API entrypoints to set the initial value
+of a global with an rvalue and to use constructors:
+
+  * :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 0f90db3..9b1eed2 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 68ab7ab..14ee57e 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 791a203..9267b6d 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``.