The unpac monorepo manager self-hosting as a monorepo using unpac
Merge pull request #14269 from MisterDA/manual-intf-c-uniform-header-quoting
manual: always refer to headers as `<caml/example.h>`
authored by
Gabriel Scherer
and committed by
GitHub
8d19f87b
aa53c7c4
+20
-20
+20
-20
manual/src/cmds/intf-c.etex
+20
-20
manual/src/cmds/intf-c.etex
···
165
165
To write C code that operates on OCaml values, the following
166
166
include files are provided:
167
167
\begin{tableau}{|l|p{12cm}|}{Include file}{Provides}
168
-
\entree{"caml/mlvalues.h"}{definition of the "value" type, and conversion
168
+
\entree{"<caml/mlvalues.h>"}{definition of the "value" type, and conversion
169
169
macros}
170
-
\entree{"caml/alloc.h"}{allocation functions (to create structured OCaml
170
+
\entree{"<caml/alloc.h>"}{allocation functions (to create structured OCaml
171
171
objects)}
172
-
\entree{"caml/memory.h"}{miscellaneous memory-related functions
172
+
\entree{"<caml/memory.h>"}{miscellaneous memory-related functions
173
173
and macros (for GC interface, in-place modification of structures, etc).}
174
-
\entree{"caml/fail.h"}{functions for raising exceptions
174
+
\entree{"<caml/fail.h>"}{functions for raising exceptions
175
175
(see section~\ref{ss:c-exceptions})}
176
-
\entree{"caml/callback.h"}{callback from C to OCaml (see
176
+
\entree{"<caml/callback.h>"}{callback from C to OCaml (see
177
177
section~\ref{s:c-callback}).}
178
-
\entree{"caml/custom.h"}{operations on custom blocks (see
178
+
\entree{"<caml/custom.h>"}{operations on custom blocks (see
179
179
section~\ref{s:c-custom}).}
180
-
\entree{"caml/intext.h"}{operations for writing user-defined
180
+
\entree{"<caml/intext.h>"}{operations for writing user-defined
181
181
serialization and deserialization functions for custom blocks
182
182
(see section~\ref{s:c-custom}).}
183
-
\entree{"caml/threads.h"}{operations for interfacing in the presence
183
+
\entree{"<caml/threads.h>"}{operations for interfacing in the presence
184
184
of multiple threads (see section~\ref{s:C-multithreading}).}
185
185
\end{tableau}
186
186
These files reside in the "caml/" subdirectory of the OCaml
···
414
414
\section{s:c-value}{The \texttt{value} type}
415
415
416
416
All OCaml objects are represented by the C type "value",
417
-
defined in the include file "caml/mlvalues.h", along with macros to
417
+
defined in the include file "<caml/mlvalues.h>", along with macros to
418
418
manipulate values of that type. An object of type "value" is either:
419
419
\begin{itemize}
420
420
\item an unboxed integer;
···
615
615
contains "h", second field "t".}
616
616
\end{tableau}
617
617
618
-
As a convenience, "caml/mlvalues.h" defines the macros "Val_unit",
618
+
As a convenience, "<caml/mlvalues.h>" defines the macros "Val_unit",
619
619
"Val_false", "Val_true" and "Val_emptylist" to refer to "()",
620
620
"false", "true" and "[]".
621
621
···
864
864
according to their size as zero-sized blocks, small blocks (with size
865
865
less than or equal to \verb"Max_young_wosize"), and large blocks (with
866
866
size greater than \verb"Max_young_wosize"). The constant
867
-
\verb"Max_young_wosize" is declared in the include file "mlvalues.h". It
867
+
\verb"Max_young_wosize" is declared in the include file "<caml/mlvalues.h>". It
868
868
is guaranteed to be at least 64 (words), so that any block with
869
869
constant size less than or equal to 64 can be assumed to be small. For
870
870
blocks whose size is computed at run-time, the size must be compared
···
936
936
\subsection{ss:c-simple-gc-harmony}{Simple interface}
937
937
938
938
All the macros described in this section are declared in the
939
-
"memory.h" header file.
939
+
"<caml/memory.h>" header file.
940
940
941
941
\begin{gcrule}
942
942
A function that has parameters or local variables of type "value" must
···
1536
1536
and macros:
1537
1537
\begin{itemize}
1538
1538
\item "value caml_get_value_or_raise(caml_result "\var{res}")"
1539
-
(in "fail.h") returns the value contained in \var{res} or reraises
1539
+
(in "<caml/fail.h>") returns the value contained in \var{res} or reraises
1540
1540
the exception it contains. In particular,
1541
1541
"(void)caml_get_value_or_raise(res)" can be used to ignore an OCaml
1542
1542
result of type "unit", yet propagate exceptions to the caller.
1543
1543
1544
-
\item "Result_value(value "\var{v}")" (in "mlvalues.h") is the result
1544
+
\item "Result_value(value "\var{v}")" (in "<caml/mlvalues.h>") is the result
1545
1545
that represents returning the value \var{v}.
1546
1546
1547
-
\item "Result_exception(value "\var{exn}")" (in "mlvalues.h") is the
1547
+
\item "Result_exception(value "\var{exn}")" (in "<caml/mlvalues.h>") is the
1548
1548
result that represents raising the exception \var{exn}.
1549
1549
1550
1550
\item "int caml_result_is_exception(caml_result "\var{res}")"
1551
-
(in "mlvalues.h") is true if \var{res} represents an exception.
1551
+
(in "<caml/mlvalues.h>") is true if \var{res} represents an exception.
1552
1552
1553
-
\item The macro "CAMLlocalresult(foo)" (in "memory.h") is the
1553
+
\item The macro "CAMLlocalresult(foo)" (in "<caml/memory.h>") is the
1554
1554
"caml_result" counterpart of "CAMLlocal1": it declares a local
1555
1555
variable of type "caml_result", whose content is tracked by the
1556
1556
OCaml GC. Just like "CAMLlocal1", it can only be used between
···
1886
1886
by calling "Printexc.record_backtrace true" in the initialization of
1887
1887
one of the OCaml modules. This can also be achieved from the C side
1888
1888
by calling "caml_record_backtraces(1);" in the OCaml-C glue code.
1889
-
("caml_record_backtraces" is declared in "backtrace.h")
1889
+
("caml_record_backtraces" is declared in "<caml/backtrace.h>")
1890
1890
1891
1891
\paragraph{Unloading the runtime.}
1892
1892
···
1906
1906
including "dynlink" plugins.
1907
1907
\item Freeing the memory blocks that were allocated by the runtime with
1908
1908
"malloc". Inside C primitives, it is advised to use "caml_stat_*" functions
1909
-
from "memory.h" for managing static (that is, non-moving) blocks of heap
1909
+
from "<caml/memory.h>" for managing static (that is, non-moving) blocks of heap
1910
1910
memory, as all the blocks allocated with these functions are automatically
1911
1911
freed by "caml_shutdown". For ensuring compatibility with legacy C stubs that
1912
1912
have used "caml_stat_*" incorrectly, this behaviour is only enabled if the
···
3023
3023
3024
3024
\subsection{ss:c-internal-macros}{OCaml version macros}
3025
3025
Finally, if including the right headers is not enough, or if you need to support
3026
-
version older than OCaml 4.04, the header file "caml/version.h" should help
3026
+
version older than OCaml 4.04, the header file "<caml/version.h>" should help
3027
3027
you to define your own compatibility layer.
3028
3028
This file provides few macros defining the current OCaml version.
3029
3029
In particular, the "OCAML_VERSION" macro describes the current version,