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

bobot · 2017-09-18T15:57:29Z

Try to add documentation for -output-complete-obj. However the comment in the latex of @damiendoligez about the doc of -output-obj is still true:

% -- This seems completely wrong -- Damien
% The shared libraries produced by "ocamlc -output-obj" or by "ocamlopt
% -output-obj" already contains the OCaml runtime library as
% well as all the needed C libraries.

I'm wondering if the documentation shoudn't be written by saying that -output-obj is deprecated and just talk about -output-complete-obj. Is there a need for the building of not shared libraries that doesn't contains the runtime and C stub?

Closes #8882

dbuenzli · 2017-09-18T16:48:04Z

is still true:

% -- This seems completely wrong -- Damien
% The shared libraries produced by "ocamlc -output-obj" or by "ocamlopt
% -output-obj" already contains the OCaml runtime library as
% well as all the needed C libraries.

AFAIR that's actually not the case, you have to link libasmrun and your libraries when you produce your executable.

Is there a need for the building of not shared libraries that doesn't contains the runtime and C stub?

You might want to link with a runtime variant.

bobot · 2017-09-19T09:12:13Z

AFAIR that's actually not the case, you have to link libasmrun and your libraries when you produce your executable.

When doing a .so (main_dll = true), the code does exactly the same thing for -output-obj and -output-complete-obj (main_obj_runtime = true) except for the linking of the C libraries of the runtime:

  let files, c_lib =
    if (not !Clflags.output_c_object) || main_dll || main_obj_runtime then
      files @ (List.rev !Clflags.ccobjs) @ runtime_lib () @ libunwind,
      (if !Clflags.nopervasives || main_obj_runtime
       then "" else Config.native_c_libraries)
    else
      files, ""

I tested it that work without linking the runtime. Perhaps a test should be added for the creation of shared libraries.

Is there a need for the building of not shared libraries that doesn't contains the runtime and C stub?

You might want to link with a runtime variant.

Differently than by using -runtime-variant? In fact -runtime-variant _pic is on some architecture needed.

Why linking with Config.native_c_libraries in -output-complete-obj since it exists shared libraries for them and the dependency are marked in the .so generated?
Does it makes sense to have a libasmrun_pic.so?

dbuenzli · 2017-09-19T13:24:39Z

Sorry I missed the shared aspect what is written as a comment there seems consistant with what is written about the worfklow here, I thought .o generation was being discussed.

That said I don't really see why -output-obj should be deprecated. I still see the runtime system as a library (providing .pc files for them would actually be nice) rather than being intrisic to the .o generated and I don't see what is wrong with resolving it at the link step --- from a build perspective if you want to produce executables with multiple variants you will have to repeat the whole work for the .o for each of the variant without that option.

bobot · 2017-09-19T15:50:05Z

That said I don't really see why -output-obj should be deprecated

Ok, it just seemed difficult to grasp the differences, but keeping the simple variant seems indeed useful.

gasche · 2017-10-19T14:49:29Z

What is the current status of this PR, is it proposed for merge?

bobot · 2017-10-19T16:00:38Z

@gasche I think it is.

gasche · 2017-10-19T16:44:54Z

@dbuenzli, do you like the current state? (Do you "approve" the PR?)

dbuenzli · 2017-10-19T16:50:39Z

manual/manual/cmds/intf-c.etex

+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


I'm not sure if the larger context defines the notion of autolink libraries. But I guess that's the C linking instructions that are embedded in ocaml object's files.

This wording is already used for the -noautolink option.

dbuenzli · 2017-10-19T16:58:05Z

manual/manual/cmds/intf-c.etex

+This use of "-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-complete-obj"


Maybe I don't understand something but isn't it the case that:

-output-obj: .{o,a} -> only the ocaml program, .so -> ocaml program + runtime libraries + autolink (?)

-output-complete-obj: .{o,a,so} -> ocaml program + runtime libraries + autolink

So I'm not sure I understand this "three possible behaviours" of -output-complete-obj.

With ocamlc a .c can be produced with the two options. And in fact a .a can never be produced.

As far as I understand, the two options -output-obj and -output-complete-obj have the same behavior when producing a shared library or a c file. Would it not make sense to mention both of them in the previous paragraph?

dbuenzli · 2017-10-19T16:59:37Z

manual/manual/cmds/intf-c.etex

@@ -1597,9 +1603,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 all C
+libraries that are required by the OCaml runtimes used.


provide the C libraries required by the OCaml runtime

dbuenzli · 2017-10-19T17:02:29Z

manual/manual/cmds/intf-c.etex

+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


I don't find that particularly intelligible and rather ambiguous, maybe camlcode.o + -lc -lm ? In particular it seems to me that should not repeat the autolink libraries here.

It is indeed strange that the autolink libraries are added but you still need the library of the runtime. It is not always -lc -lm it could be -lm -ldl, no? I can't add $(ocamlopt -config | sed -n -e "s/^native_c_libraries:$.*$$/\1/p") so perhaps {\it{C libraries required by the runtime, eg -lm -ldl}}.

I was just suggesting examples of what you may need to add here. It's just that it should be made clear that you should not add the autolink libs otherwise you will be subject to double linking. I just find that not very clear in the current text.

(Aside. For this reason I personally find the behaviour of -output-complete-obj dubious, you may have other C object files at that point that need the C libs that you autolinked via -output-complete-obj).

(In your case you are not the target audience for -output-complete-obj.)

dbuenzli · 2017-10-19T17:02:56Z

manual/manual/cmds/intf-c.etex

+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


Same comment as above.

bobot · 2017-10-24T14:27:44Z

I don't understand why -output-complete-obj doesn't add -lm -ldl for the linking of a .so like -output-obj because currently they don't appear in the list of dependency of the resulting .so using ldd.

gasche · 2017-10-26T07:32:24Z

So what's the current status of this? It looks like you are both slightly confused about some of the aspects of -output-complete-obj we are discussing documenting ( @whitequark might chime in ). Do you think it is more valuable to include a maybe-not-perfect documentation in 4.06, or to delay until you have something you both like?

dbuenzli · 2017-10-26T07:40:51Z

Do you think it is more valuable to include a maybe-not-perfect documentation in 4.06, or to delay until you have something you both like?

I think that it would valuable to have correct and precise documentation and whoever added that command line switch should do it.

Octachron · 2018-03-18T14:10:10Z

Reading the original mantis ticket, it seems to me that the original intent was to not link -ldl when building a .o object file. @whitequark , do you agree with me that it would be fine to add back -lm -ldl when linking a .so file?

whitequark · 2018-03-18T14:45:48Z

@Octachron I agree.

nojb · 2019-09-24T09:40:39Z

We should try to merge this PR even if not perfect. But it needs to be updated for #8872 (if that PR is merged before).

damiendoligez · 2020-02-14T14:34:12Z

@bobot #8872 was merged in the meantime. Do you want to update this PR?

bobot · 2020-02-15T22:52:02Z

@nojb Could you do the update? You already have the right to modify my repo.

nojb · 2020-10-13T20:43:34Z

Circling back to this one, I note that #8872 actually introduced a different flag (-output-complete-exe) so it is not relevant here. On the other hand, #1664 cleared up one subtle point about -output-complete-obj vs -output-obj. I will update the PR accordingly.

nojb · 2020-10-14T03:33:55Z

PR rebased. Formal review/approval would be appreciated.

damiendoligez

Grammar corrections, cut long lines, and some rewording for the byte-code case. This PR is nearly ready for merge.

manual/manual/cmds/intf-c.etex

manual/manual/cmds/native.etex

manual/manual/cmds/unified-options.etex

manual/manual/cmds/intf-c.etex

nojb · 2021-01-16T15:58:02Z

Thanks for the review @damiendoligez! I think all points have been addressed.

damiendoligez · 2021-02-08T15:23:53Z

Good. All we need now is a rebase and a Changes entry (if you think it's needed).

nojb · 2021-02-08T16:38:37Z

Good. All we need now is a rebase and a Changes entry (if you think it's needed).

Done. Good to go once CI is green.

Co-authored-by: Thibaut Mattio <thibaut.mattio@gmail.com>

bobot mentioned this pull request Sep 18, 2017

[OCamlc] fixes output-complete-object #1332

Merged

damiendoligez added this to the 4.06.0 milestone Sep 25, 2017

gasche closed this Sep 27, 2017

gasche reopened this Sep 27, 2017

bobot changed the title ~~WIP: [Doc] adds for -output-complete-obj option~~ [Doc] adds for -output-complete-obj option Oct 19, 2017

dbuenzli suggested changes Oct 19, 2017

View reviewed changes

gasche modified the milestones: 4.06.0, 4.07-or-later Oct 27, 2017

bobot mentioned this pull request Feb 2, 2018

[WIP] Executables define rule for C object files (-output-obj) ocaml/dune#23

Merged

2 tasks

damiendoligez added the high-priority label Mar 1, 2018

damiendoligez assigned Octachron Mar 1, 2018

Octachron mentioned this pull request Mar 19, 2018

output-complete-obj: link runtime C libraries when building shared libraries #1664

Merged

damiendoligez removed this from the consider-for-4.07 milestone Jun 5, 2018

Octachron mentioned this pull request Aug 21, 2019

-output-complete-obj is not documented in the manual #8882

Closed

nojb mentioned this pull request Sep 24, 2019

Extend ocamlc -output-complete-obj to build .exe #8872

Merged

dinosaure mentioned this pull request Jun 16, 2020

Add documentation mirage/mirage#1168

Merged

nojb force-pushed the output_obj_doc branch from 3c385ef to ee1c592 Compare October 14, 2020 03:03

damiendoligez requested changes Jan 14, 2021

View reviewed changes

nojb force-pushed the output_obj_doc branch from ee1c592 to 29b76fd Compare January 16, 2021 15:56

damiendoligez approved these changes Feb 8, 2021

View reviewed changes

bobot and others added 4 commits February 8, 2021 16:27

[Doc] adds for -output-complete-obj option

fbaa77a

[Manual] Fixes from @dbunzli review

c58f1b0

Review

5e059dd

Changes

4c3a935

nojb force-pushed the output_obj_doc branch from 29b76fd to 4c3a935 Compare February 8, 2021 15:30

nojb merged commit 841607f into ocaml:trunk Feb 8, 2021

garrigue pushed a commit to garrigue/ocaml that referenced this pull request Mar 3, 2021

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

0da81c4

smuenzel pushed a commit to smuenzel/ocaml that referenced this pull request Mar 30, 2021

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

377f90a

EmileTrotignon pushed a commit to EmileTrotignon/ocaml that referenced this pull request Jan 12, 2024

Add attribution to blog posts (ocaml#1351)

007e187

Co-authored-by: Thibaut Mattio <thibaut.mattio@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

bobot commented Sep 18, 2017 •

edited by nojb

dbuenzli commented Sep 18, 2017

bobot commented Sep 19, 2017

dbuenzli commented Sep 19, 2017

bobot commented Sep 19, 2017

gasche commented Oct 19, 2017

bobot commented Oct 19, 2017

gasche commented Oct 19, 2017

dbuenzli Oct 19, 2017

bobot Oct 24, 2017

dbuenzli Oct 19, 2017

bobot Oct 24, 2017

Octachron Mar 18, 2018

dbuenzli Oct 19, 2017

dbuenzli Oct 19, 2017

bobot Oct 24, 2017

dbuenzli Oct 24, 2017

whitequark Oct 28, 2017

dbuenzli Oct 19, 2017

bobot commented Oct 24, 2017

gasche commented Oct 26, 2017

dbuenzli commented Oct 26, 2017

Octachron commented Mar 18, 2018

whitequark commented Mar 18, 2018

nojb commented Sep 24, 2019

damiendoligez commented Feb 14, 2020

bobot commented Feb 15, 2020

nojb commented Oct 13, 2020

nojb commented Oct 14, 2020

damiendoligez left a comment

nojb commented Jan 16, 2021

damiendoligez commented Feb 8, 2021

nojb commented Feb 8, 2021

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

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

Conversation

bobot commented Sep 18, 2017 • edited by nojb

dbuenzli commented Sep 18, 2017

bobot commented Sep 19, 2017

dbuenzli commented Sep 19, 2017

bobot commented Sep 19, 2017

gasche commented Oct 19, 2017

bobot commented Oct 19, 2017

gasche commented Oct 19, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bobot commented Oct 24, 2017

gasche commented Oct 26, 2017

dbuenzli commented Oct 26, 2017

Octachron commented Mar 18, 2018

whitequark commented Mar 18, 2018

nojb commented Sep 24, 2019

damiendoligez commented Feb 14, 2020

bobot commented Feb 15, 2020

nojb commented Oct 13, 2020

nojb commented Oct 14, 2020

damiendoligez left a comment

Choose a reason for hiding this comment

nojb commented Jan 16, 2021

damiendoligez commented Feb 8, 2021

nojb commented Feb 8, 2021

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

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

bobot commented Sep 18, 2017 •

edited by nojb