[Doc] adds for -output-complete-obj option (#1351)

Changes

@@ -91,6 +91,10 @@ Working version
   library module's documentation.
   (John Whitington, review by David Allsopp)
 
+- #1351: Document `-output-complete-obj` option in the manual.
+  (François Bobot, Nicolás Ojeda Bär, review by Daniel Bünzli and Damien
+  Doligez)
+
 ### Compiler user-interface and warnings:
 
 - #9960: extend ocamlc/ocamlopt's -o option to work when compiling C files

man/ocamlc.m

@@ -526,6 +526,8 @@ object code files (.cmo), libraries (.cma), and C libraries specified
 option is given, specify the name of the
 packed object file produced.  If the
 .B \-output\-obj
+or
+.B \-output\-complete\-obj
 option is given,
 specify the name of the output file produced.
 This can also be used when compiling an interface or implementation
@@ -559,6 +561,12 @@ object code files (.cmo), libraries (.cma), and C libraries specified
 option can also be used to produce a C source file (.c extension) or
 a compiled shared/dynamic library (.so extension).
 .TP
+.B \-output\-complete\-obj
+Same as
+.B \-output\-obj
+except when creating an object file where it includes the runtime and
+autolink libraries.
+.TP
 .B \-pack
 Build a bytecode object file (.cmo file) and its associated compiled
 interface (.cmi) that combines the object

man/ocamlopt.m

@@ -475,6 +475,12 @@ object code files (.cmx), and libraries (.cmxa). See also option
 option.
 This option can also be used to produce a compiled shared/dynamic
 library (.so extension).
+.B \-output\-complete\-obj
+Same as
+.B \-output\-obj
+except the object file produced includes the runtime and
+autolink libraries.
+.TP
 .TP
 .B \-pack
 Build an object file (.cmx and .o files) and its associated compiled

manual/src/cmds/comp.etex

@@ -114,7 +114,7 @@ These ".cmt" and ".cmti" files are typically useful for code inspection tools.
 \section{s:comp-options}{Options}
 
 The following command-line options are recognized by "ocamlc".
-The options "-pack", "-a", "-c" and "-output-obj" are mutually exclusive.
+The options "-pack", "-a", "-c", "-output-obj" and "-output-complete-obj" are mutually exclusive.
 % Define boolean variables used by the macros in unified-options.etex
 \newif\ifcomp \comptrue
 \newif\ifnat \natfalse

manual/src/cmds/intf-c.etex

@@ -1627,12 +1627,15 @@ section~\ref{ss:main-c}, this means that "argv[0]" or "argv[1]" must
 contain the executable file name.
 
 An alternative is to embed the bytecode in the C code. The
-"-output-obj" option to "ocamlc" is provided for this purpose.  It
-causes the "ocamlc" compiler to output a C object file (".o" file,
-".obj" under Windows) containing the bytecode for the OCaml part of the
-program, as well as a "caml_startup" function. The C object file
-produced by "ocamlc -output-obj" can then be linked with C code using
-the standard C compiler, or stored in a C library.
+"-output-obj" and "-output-complete-obj" options to "ocamlc" are
+provided for this purpose. They cause the "ocamlc" compiler to output a
+C object file (".o" file, ".obj" under Windows) containing the
+bytecode for the OCaml part of the program, as well as a
+"caml_startup" function. The C object file produced by "ocamlc
+-output-complete-obj" also contains the runtime and autolink
+libraries. The C object file produced by "ocamlc -output-obj" or
+"ocamlc -output-complete-obj" can then be linked with C code using the
+standard C compiler, or stored in a C library.
 
 The "caml_startup" function must be called from the main C program in
 order to initialize the OCaml runtime and execute the OCaml
@@ -1648,23 +1651,30 @@ C code by instead using the "caml_startup_exn" function and testing the result
 using {\tt Is_exception_result} (followed by {\tt Extract_exception} if
 appropriate).
 
-The "-output-obj" option can also be used to obtain the C source file.
-More interestingly, the same option can also produce directly a shared
-library (".so" file, ".dll" under Windows) that contains the OCaml
-code, the OCaml runtime system and any other static C code given to
-"ocamlc" (".o", ".a", respectively, ".obj", ".lib"). This use of
-"-output-obj" is very similar to a normal linking step, but instead of
-producing a main program that automatically runs the OCaml code, it
-produces a shared library that can run the OCaml code on demand. The
-three possible behaviors of "-output-obj" are selected according
-to the extension of the resulting file (given with "-o").
+The "-output-obj" and "-output-complete-obj" options can also be used to
+obtain the C source file.
+More interestingly, these options can also produce
+directly a shared library (".so" file, ".dll" under Windows) that
+contains the OCaml code, the OCaml runtime system and any other static
+C code given to "ocamlc" (".o", ".a", respectively, ".obj", ".lib").
+This use of "-output-obj" and "-output-complete-obj"
+is very similar to a normal linking
+step, but instead of producing a main program that automatically runs
+the OCaml code, it produces a shared library that can run the OCaml
+code on demand. The three possible behaviors of "-output-obj"
+and "-output-complete-obj"
+(to produce a C source code ".c", a C object file ".o", a shared library ".so"),
+are selected according to the extension of the resulting file (given
+with "-o").
 
 The native-code compiler "ocamlopt" also supports the "-output-obj"
-option, causing it to output a C object file or a shared library
-containing the native code for all OCaml modules on the command-line,
-as well as the OCaml startup code. Initialization is performed by
-calling "caml_startup" (or "caml_startup_exn") as in the case of the
-bytecode compiler.
+and "-output-complete-obj" options, causing it to output a C object
+file or a shared library containing the native code for all OCaml
+modules on the command-line, as well as the OCaml startup code.
+Initialization is performed by calling "caml_startup" (or
+"caml_startup_exn") as in the case of the bytecode compiler. The file
+produced by "ocamlopt -output-complete-obj" also contains the runtime
+and autolink libraries.
 
 For the final linking phase, in addition to the object file produced
 by "-output-obj", you will have to provide the OCaml runtime
@@ -1689,9 +1699,27 @@ With "ocamlopt", you should do:
 % -output-obj" already contains the OCaml runtime library as
 % well as all the needed C libraries.
 
+For the final linking phase, in addition to the object file produced
+by "-output-complete-obj", you will have only to provide the C
+libraries required by the OCaml runtime.
+
+For instance, assume the OCaml part of your program uses the
+Unix library.  With "ocamlc", you should do:
+\begin{alltt}
+        ocamlc -output-complete-obj -o camlcode.o unix.cma {\it{other}} .cmo {\it{and}} .cma {\it{files}}
+        cc -o myprog {\it{C objects and libraries}} \char92
+           camlcode.o {\it{C libraries required by the runtime, eg -lm  -ldl -lcurses -lpthread}}
+\end{alltt}
+With "ocamlopt", you should do:
+\begin{alltt}
+        ocamlopt -output-complete-obj -o camlcode.o unix.cmxa {\it{other}} .cmx {\it{and}} .cmxa {\it{files}}
+        cc -o myprog {\it{C objects and libraries}} \char92
+           camlcode.o {\it{C libraries required by the runtime, eg -lm -ldl}}
+\end{alltt}
+
 \paragraph{Warning:} On some ports, special options are required on the final
 linking phase that links together the object file produced by the
-"-output-obj" option and the remainder of the program.  Those options
+"-output-obj" and "-output-complete-obj" options and the remainder of the program.  Those options
 are shown in the configuration file "Makefile.config" generated during
 compilation of OCaml, as the variable "OC_LDFLAGS".
 \begin{itemize}
@@ -2341,7 +2369,7 @@ code around C calls.  Technically it wraps every C call with the C function
 For small functions that are called repeatedly, this indirection can have
 a big impact on performances.  However this is not needed if we know that
 the C function doesn't allocate, doesn't raise exceptions, and doesn't release
-the master lock (see section~\ref{ss:parallel-execution-long-running-c-code}).  
+the master lock (see section~\ref{ss:parallel-execution-long-running-c-code}).
 We can instruct the OCaml native-code compiler of this fact by annotating the
 external declaration with the attribute "[\@\@noalloc]":
 

manual/src/cmds/native.etex

@@ -102,8 +102,8 @@ These ".cmt" and ".cmti" files are typically useful for code inspection tools.
 \section{s:native-options}{Options}
 
 The following command-line options are recognized by "ocamlopt".
-The options "-pack", "-a", "-shared", "-c" and "-output-obj" are mutually
-exclusive.
+The options "-pack", "-a", "-shared", "-c", "-output-obj" and
+"-output-complete-obj" are mutually exclusive.
 
 % Configure boolean variables used by the macros in unified-options.etex
 \compfalse

manual/src/cmds/unified-options.etex

@@ -444,8 +444,8 @@ Specify the name of the output file produced by the
 default output name is "a.out" under Unix and "camlprog.exe" under
 Windows. If the "-a" option is given, specify the name of the library
 produced.  If the "-pack" option is given, specify the name of the
-packed object file produced.  If the "-output-obj" option is given,
-specify the name of the output file produced.
+packed object file produced.  If the "-output-obj" or "-output-complete-obj"
+options are given, specify the name of the output file produced.
 \nat{If the "-shared" option is given, specify the name of plugin
 file produced.}
 \comp{If the "-c" option is given, specify the name of the object
@@ -512,6 +512,12 @@ is embedded in the C code so it is no longer accessible to tools such as
 "ocamldebug". On the other hand, the resulting binary is resistant to "strip".
 }%comp
 
+\notop{%
+\item["-output-complete-obj"]
+Same as "-output-obj" options except the object file produced includes the
+runtime and autolink libraries.
+}%notop
+
 \nat{%
 \item["-pack"]
 Build an object file (".cmx" and ".o"/".obj" files) and its associated compiled