This addresses PR#6475.
In 4.02 the behavior of ocamlc/ocamlopt with regards to these options
was as follows:
* options and arguments are parsed left-to-right in the exact order
in which they are passed, with compilation taking into account
only the options leftwards from it;
* "foo.c" is compiled to "foo.o" in current directory;
* when "-c" is not specified:
* "foo.ml" is compiled to "foo.cmo"/"foo.cmxo"
in current directory;
* after all files have been compiled, if any .ml files are passed,
all provided files are linked as:
* when "-o" is not specified: "a.out" in current directory;
* when "-o out" is specified: "out".
* when "-c" is specified:
* "foo.ml" is compiled to:
* when "-o" is not specified: "foo.cmo"/"foo.cmxo"
in current directory;
* when "-o out" is specified: "out.cmo"/"out.cmxo";
and then compilation proceeds as if the last "-o" option
has disappeared.
* no final link is performed.
The behavior where the build product of the C sources always ended up
in the current directory was problematic: it required buildsystem
hacks to move the file in its proper place and ultimately was racy,
as multiple files with the same basename in different directories
may well end up overwriting each other with e.g. ocamlbuild.
On top of that, the behavior was quite confusing, since it is not
only stateful and dependent on argument order, but also the mere act
of compilation changed state.
The commit 1d8e590c has attempted to rectify that by looking at
the "-o" option when compiling C files, too. After that commit,
the behavior of ocamlc/ocamlopt was as follows (only the handling
of C files was changed, but the entire chart is provided for
posterity):
* options and arguments are parsed left-to-right in the exact order
in which they are passed, with compilation taking into account
only the options leftwards from it;
* "foo.c" is compiled to:
* when "-o" is not specified: "foo.o" in current directory;
* when "-o out" is specified: "out".
* when "-c" is not specified:
* "foo.ml" is compiled to "foo.cmo"/"foo.cmxo"
in current directory;
* after all files have been compiled, if any .ml files are passed,
all provided files are linked as:
* when "-o" is not specified: "a.out" in current directory;
* when "-o out" is specified: "out".
* when "-c" is specified:
* "foo.ml" is compiled to:
* when "-o" is not specified: "foo.cmo"/"foo.cmxo"
in current directory;
* when "-o out" is specified: "out.cmo"/"out.cmxo";
and then compilation proceeds as if the last "-o" option
has disappeared.
* no final link is performed.
There is a non-obvious bug here. Specifically, what happens if more
than one C source file is passed together with a "-o" option? Also,
what happens if a C source file is passed together with a "-o" option
and then a final link is performed? The answer is that
the intermediate build product gets silently overwritten, with quite
opaque errors as a result.
There is some code (and even buildsystems) in the wild that is relying
on the fact that the -o option does not affect compilation of C source
files, e.g. by running commands such as (from ocamlnet):
ocamlc -custom -o t tend.c t.ml
It might seem that the solution would be to make the behavior of
the compiler drivers for C files match that for the OCaml files;
specifically, pretend that the "-o" option has disappeared once
the C compiler has written a build product to the specified place.
However, this would still break the existing code, and moreover
does not address the underlying problem: that the option parsing
of the OCaml compiler driver is confusing and prone to creating
latent bugs.
Instead, this commit finishes (after 1d8e590c and 55d2d420) overhauls
the way option parsing in ocamlc/ocamlopt works to behave as follows:
* options are parsed left-to-right in the order they are specified;
* after all options are parsed, arguments are parsed left-to-right
in the order they were specified;
* when "-o out" and "-c" are specified:
* when more than one file is passed, an error message
is displayed.
* when one file is passed:
* "foo.c" is compiled to "out";
* "foo.ml" is compiled to "out.cmo"/"out.cmxo".
* when "-o out" is not specified or "-c" is not specified:
* "foo.c" is compiled to "foo.o" in current directory;
* "foo.ml" is compiled to "foo.cmo"/"foo.cmxo"
in current directory;
* when "-c" is not specified:
* after all files have been compiled, if any .ml files are passed,
all provided files are linked as:
* when "-o" is not specified: "a.out" in current directory;
* when "-o out" is specified: "out".
In short, the combination of "-o", "-c" and a single source file
compiles that one file to the corresponding intermediate
build product. Otherwise, passing "-o" will either set the name of
the final build product only or error out.
This preserves compatibility with old code, makes the handling of
C and OCaml sources consistent, and overall makes the behavior
of the option parser more straightforward. However, this may break
code that relies on the fact that options are parsed in-order, e.g.
ocamlc -o t a.ml -g b.ml
where debug info would be built only for "b.ml".
Some alternative implementation paths I have considered:
* Collect the C sources and process them after OCaml sources,
while paying attention to any "-o" or "-c" that may have
been set. This doesn't work because compilation of C sources
is also affected by many flags, e.g. "-I", and so this would
have the same drawbacks but none of the benefits;
* Compile C and OCaml sources in-order as usual, but error out
when an improper combination of flags is encountered in
the middle of a compilation. This is technically feasible,
and is the option that maximally preserves compatibility, but
it is very complex: it doubles the amount of implicitly mutated
global state, and there's no guarantee I will get all edge
cases right. Moreover, the option parsing remains confusing,
and I strongly believe that the current behavior should not
remain in place.
On top of that it is hard to imagine cases where setting new options
in the middle of compilation would actually be desirable, because
this mechanism is very inexpressive: it can only add new options and
option values, since there is no way to negate or clear most of
the driver's state. Most likely is that any code that does so,
does it in error and remains operational by pure chance.
The behavior of ocamlc and ocamlopt drivers before this commit is
that the command-line options and arguments are processed exactly
sequentially; encountered options (e.g. "-o") modify the state of
the driver, and encountered arguments (e.g. "t.ml") compile
the corresponding file with whatever state the driver had at the time.
This can be quite confusing, because compiler drivers (e.g. gcc/g++,
clang/clang++, rustc, javac, go, ...) either parse the entire command
line before going on to compile files or reject options after
the first argument (only in the case of go). Thus the behavior
of ocamlc and ocamlopt is unexpected.
The following commit provides another reason for this change.
This commit adds (**) as a special empty documentation comment that
can influence the attachment of other documentation comments but is
never emitted as an attribute in the parsetree. An important use of
this empty comment would be to attach a documentation comment to the
type t and not its last constructor Label, without spurious empty
attribute, in the following construction:
type t = Label (**)
(**doc for t*)
This option was broken, as can be seen by using it to compile the
following helloworld.ml program:
let _ = Printf.printf "Hello, world!\n%!"
Then from OCaml's toplevel source directory, compile as follows:
./ocamlc.opt -use-runtime ${HOME}/src/ocaml/byterun/ocamlrun \
-nostdlib -I stdlib -o helloworld.byte helloworld.ml
And do:
head -1 helloworld.byte
See the double #! at the beginning of the line.
The first one comes from the "header" file which is included and is
correct (it would be a different header on Windows).
The second one is hard-coded and should be removed, this is what
this patch does.
Previously, `ocamlc`, `ocamlopt`, `ocamllex`, and `ocamldep` defaulted
to the bytecode versions of the tools. However, there is normally no
advantage to the bytecode versions if the native-code versions are
available, except in unusual circumstances. Instead, install the
native-code versions without the `.opt` suffix. They are still
installed with the `.opt` suffix for backwards compatibility. Finally,
install the bytecode versions with the `.byte` suffix, and build
native-code versions of tools that are not currently built in native
code.
Also, remove some duplication in tools/Makefile.shared.
Supersedes GPR #512.
alainfrisch
Jacques Garrigue
Gabriel Scherer
Hannes Mehnert
Damien Doligez
Mark Shinwell
Mark Shinwell
octachron
Leo White
Sébastien Hinderer
whitequark
Fourchaux
John Whitington
Damien Doligez
Demi Obenour
David Allsopp