Changes

Add -set-runtime-default

Allows the default location used by the bytecode runtime for the
Standard Library to be overridden when creating bytecode executables.

Bootstrap

Use %standard_library_default in Config

Config.standard_library_default is now implemented using the
%standard_library_default primitive. This allows a convenient test which
can be added for `-set-runtime-default`.

The change also makes the host-like nature of of
Config.standard_library_default clearer, as the build of the
cross-compiler must now (correctly) specify the location of its (target)
Standard Library.

Bootstrap

Allow libdir to be found relative to bindir

When configured with --with-relative-libdir, the runtime uses the
directory of the executable to determine the location of the Standard
Library. Thus, ocamlrun and the compilers look for ../lib/ocaml by
default.

This is implemented by changing caml_standard_library_default to be a
relative path, and then computing the actual value at startup (for
bytecode) and when queried (for native).

Executables (and objects) produced by the compiler always have an
absolute value of caml_standard_library_default. ocamlc.opt and
ocamlopt.opt are built using -set-runtime-default to force
caml_standard_library_default to be a relative value.

Update the installation test for enable-relative

Test --with-relative-libdir in CI

NFPR: fully test --with-relative-libdir in AppVeyor

NFPR: fully test --with-relative-libdir in precheck

Add Config.as_is_cc

Indication as to whether ocamlopt assembles files via the C compiler or
by calling the assembler directly.

Use as directly on Cygwin, as on Linux

Detect but ignore -fdebug-prefix-map on mingw-w64

mingw-w64 is based on GCC, so supports -fdebug-prefix-map, but the test
for it is skipped in configure. The test is no longer skipped (which
means that Config.c_has_debug_prefix_map returns true) but the flag is
still explicitly not used by the compilers (as before).

Increase reproducibility of relative artefacts

Simplify the computation for the runtime name

Permit single-quotes in prefix

Minor tweaks needed to allow configuring, say, for "$PWD/install'd here"

ocamlobjinfo: display the runtime used by an image

ocamlobjinfo now parses both RNTM and shebang lines in order to display
the runtime being used by a bytecode executable.

Add -launch-method to ocamlc

When linking a normal bytecode executable, allows an explicit selection
of either the executable or shebang header, regardless of the value in
runtime-launch-info.

Test both bytecode header methods

Remove metadata from runtime-launch-info

-launch-method encapsulates the first line of runtime-launch-info. The
argument to -launch-method is extended slightly to encompass the second
line, thus `-launch-method 'sh /usr/local/bin'` represents the default
runtime-launch-info file on Unix. Additional fields are added to Config
so that the installed compiler simply uses default values, rather than
reading the two lines from runtime-launch-info. The build of the
compiler itself explicitly uses `-launch-method`, which leaves only the
executable launcher compiled from stdlib/header.c in
runtime-launch-info.

Factor out the exec code in stdlib/header.c

Add -runtime-search to ocamlc

-runtime-search {disable|enable|always} adds new features to the
launcher used for bytecode executables which do not embed their own
runtime. By default, the header continues to behave as before - the
launcher will attempt to start the runtime using the absolute path which
the compiler was configured with.

The new search mode will then search for the runtime first in the
directory containing the running executable and then in PATH.

Test all three bytecode search methods

Determine Runtime ID values in configure

Mangle the bytecode runtime executable names

New option --disable-suffixing controls whether the build should use any
of the computed values for mangling its own files.

Build suffixed shared runtimes

New names for libcamlrun_shared.so and libasmrun_shared.so without the
_shared suffix and using the target triplet and runtime ID. Both ocamlc
and ocamlopt explicitly recognise `-runtime-variant _shared` and select
the correct name.

Symbolic links for libcamlrun_shared.so and libasmrun_shared.so to allow
any C programs which linked against the the output of `-output-obj` to
continue to work.

Add runtime suffixes to bytecode stub libraries

ocamlc -dllib-suffixed appends the runtime's host triplet and bytecode
runtime ID to the supplied name when searching for the DLL, and records
the base name only in .cma / executable files.

ocamlmklib -suffixed instructs ocamlmklib to use -dllib-suffixed when
generating .cma files instead of -dllib.

The effect is that stub libraries built this way have names which will
be unique for a given configuration of OCaml and so will be ignored by
other runtimes.

Bootstrap

Post-bootstrap cleanup

boot/ocamlc now supports everything that the main compiler supports.

Add --enable-runtime-search[-target] options

--enable-runtime-search controls the -runtime-search setting used to
build the compiler's own bytecode executables;
--enable-runtime-search-target controls the default value of
-runtime-search that ocamlc itself uses.

Update the installation test for runtime-searching

Make Windows header absolute (as on Unix)

Test --enable-runtime-search in CI

NFPR: fully test --enable-runtime-search in precheck

Exclude the manual from git-archive tarballs

Exclude irrelevant files from git-archive

CI scripts and Git configuration aren't required on end-user machines.

Exclude tests from git-archive tarballs

All the programs and infrastructure remain, but the tests are removed.

Don't explicitly install toplevel/byte/*.cmi

All of the .mli files in toplevel/byte are "common", so they're already
installed by the patterns in toplevel.

Don't explicitly install main.cmx and optmain.cmx

It's necessary to install main.o and optmain.o because the two modules
are not part of ocamlbytecomp.cmxa and ocamloptcomp.cmxa, but the .cmx
files are already installed as part of wildcard patterns on driver/

Remove duplicate installation in installopt

The ocamldoc installation commands in installopt duplicate a series of
commands which already happen in install.

Don't install ocamldoc's .cmi files twice

Use implicit names when installing ocamldoc

The ocamldoc binaries were installed using a relative path. They're the
only binaries installed that way - switch them to use an implicit path,
as it's easier to make an implicit path subsequently relative if needed
than vice versa.

Eliminate local for loops in install

Continue to use for when invoking recursive make calls, but use
$(foreach ..) to generate command sequences so that macros can be used
in them.

Eliminate local if blocks in install

Remove invalid directory in source install

Line was added (with typo) in PR#8925 (4.09) and should have been
removed as part of PR#10355 (4.13)

Sprinkle some meta-programming on the install target

Keep the stripped bytecode binaries

No need to remove things during install when it will be done later by a
package manager. Also prepares for the possibility of letting something
else install the binary subsequently.

Straighten out the INSTALL_* Makefile variables

Move various definitions around such that merged Makefile variables are
all in Makefile.common. Sanitise the names to be closer to
INSTALL_LIBDIR_subdirname.

Remove the recursive invocation in install targets

Add SUBDIR_NAME to principal Makefiles

SUBDIR_NAME goes along with ROOTDIR - where ROOTDIR is the relative path
from Makefile back to the root directory, SUBDIR_NAME is the implicit
path from the root directory to Makefile.

Use macros to generate installation commands

make install works as it did before. All the commands in the install
targets now go through a macro call which allows the semantic intent of
each command to be more clearly specified.

Add additional modes to make install

make [INSTALL_MODE=install] install
  - installs the compiler, as normal
make INSTALL_MODE=display install
  - displays the operations needed for
make INSTALL_MODE=list install
  - lists the files and symbolic links which are installed

Generate an opam .install file and support script

make INSTALL_MODE=opam install generates $OPAM_PACKAGE_NAME.install and
$OPAM_PACKAGE_NAME-fixup.sh ($OPAM_PACKAGE_NAME defaults to
ocaml-compiler). Nothing is installed by this mode. The fixup.sh script
is intentionally not made executable (it should be invoked explicitly
with sh) and creates symbolic links, if required, and also manually
copies the files to the doc dir, as the .install file format doesn't
allow the correct location to be specified.

Experimentally, use it

Generate a relocatable cloning script

Got an interpreter, and we're not afraid to use it

Mark winpthreads dependency as Windows-only

Redundant filter, but mitigates an issue with --assume-built in opam

Mark input dependencies as build

Mitigates an issue with opam install --assume-built since build
dependencies are ignored. The semantics should remain consistent: in
particular, as there is only a single version of each of these packages,
the key issue is that removing the package will still trigger the
correct behaviour as the dependency graph will change.

Test opam in CI

Generator script for ocaml.config in opam

This script is installed in opam by the ocaml-config package and then
used by its ocaml virtual packages to probe the compiler installation
and record various pieces of information about it by generating
ocaml.config

Remove need for shared libraries in ocaml-config

Update ocaml-config for 4.12 scheme

- Versioning numbering used for pre-releases now uses ~ instead of +
- Support the new ocaml-option- package layout

OCaml 3.07 version of gen_ocaml_config.ml.in

Windows fixes to ocaml-config

- Wrong separator used for generating CAML_LD_LIBRARY_PATH on Windows
- Fixed detection for the native-tools variable on Windows
- Support dkml-base-compiler

Update ocaml-config for the new OCaml 5 layout

Fully unify and update gen_ocaml_config.ml

There was technically a slightly tailored version of gen_ocaml_config.ml
sitting in the history to support the OCaml 3.07 package (which is the
oldest compiler archived in opam-repository).

The ocaml-config package originally stored this script in the files/
subdirectory, but policy changes in 2025 mean it was being referenced
from an archive repository. This script can now be referenced directly
by opam's ocaml package, removing the need for an additional package in
the dependency cone and also meaning that the script no longer has to be
installed in the switch.

The substs mechanism has been replaced in favour of passing the required
arguments on the command line. The previous mechanism was an artefact of
the way this script was previously generated, rather than necessarily a
clear way of writing it. It means this script is now simply an OCaml
script and has the added benefit of allowing each ocaml package to
specify the appropriate additional version components (e.g. spacetime,
nnp, etc.) rather than having each script confusingly containing all of
them.

Support relative paths in gen_ocaml_config.ml

Remove the MAX_PATH limit in header.c on Windows

Move caml_search_dll_in_path to dynlink.c

Eliminates code duplication between unix.c and win32.c

Remove caml_cds_file

OCaml 4.x global which should have been removed with OCaml 5.0

header.c: handle parasitic case of argc < 1

Remove unnecessary Cygwin path workarounds

This is no longer required (nor does it work). Cygwin 1.5.20 (July 2006)
added the transparent_exe option to the CYGWIN environment variable which
made open behave in the same way as stat. Cygwin 1.7.1 (December 2009 and,
despite the version number, the first release of Cygwin 1.7) made this
behaviour default (and removed the ability to turn it off).

header.c: malloc the result of searchpath

Move searchpath from header.c into the runtime

Merge the path-searching code from stdlib/header.c with the runtime's
version.

Use caml_executable_name in header.c

Don't check for shebang scripts on Windows

Bytecode startup includes a check which has no place on Windows.

Simplify the interface of caml_attempt_open

Previously, caml_attempt_open received a pointer to the string and
passed this string to caml_search_exe_in_path. This function allocates a
fresh string which was then assigned to that pointer.

This interface was a little cryptic to follow - in particular, there
were several scenarios in which the result was not being freed. It's
also not entirely clear that caml_attempt_open involved a PATH-search,
which appears to have been applied in error when CAML_DEBUG_FILE was
added.

Preserve argv[0] on Unix in the executable header

Makes the behaviour of the Unix and Windows versions of the header
equivalent, in particular it means that if argv[0] doesn't describe the
executable, more things fail for Cygwin.

Fix STARTUPINFO structure in stdlib/header.c

If a CRT application (including, therefore, another OCaml program),
exec's a bytecode program which uses the executable header, the
cbReserved2 and lpReserved2 fields of the STARTUPINFO structure are
quietly used by the CRT to pass handle information about open fds.

The status checker in the cloexec.ml test has C stubs, which causes
ocamltest to compile the bytecode version with -custom. The test is
split to have an additional intermediate pure OCaml program which simply
repeats either the Unix.execv or Unix.create_process call with the
Sys.argv it was applied. In bytecode, ocamltest compiles this program
just with -use-runtime, which means it uses the executable header on
Windows.

Without the change to header.c in this commit, that test begins to fail
in bytecode on Windows, because the CRT information about inherited
handles is not passed on to the status checker (the HANDLE values will
have been inherited, as that's a kernel function, but the CRT structures
regarding the fds are not initialised, which is what the checker than
looks at).

The fix here simplifies the code considerably - rather than initialising
a fresh STARTUPINFO structure, we simply use GetStartupInfo to retrieve
the one which was used to create the process itself and pass that to
CreateProcess - cbReserved2 and lpReserved2 are therefore passed on, and
the cloexec.ml test passes again.

Share image fd between header.c and startup_byt.c

The bytecode executable launcher (stdlib/header.c) can _only_ invoke
ocamlrun after it has opened itself in order to find out the name of the
runtime to execute. However, once ocamlrun is exec'd, the knowledge of
this file was previously lost and if it could not be recovered from
argv[0], then execution fails.

This new approach, for both Windows and Unix, instead keeps the fd for
the bytecode image open and passes its number to ocamlrun as
__OCAML_EXEC_FD in the environment. ocamlrun detects this environment
variable and uses that fd to load the bytecode image. If this fails, the
runtime does _not_ fallback to any other mechanisms.

On Windows, it is possible to recover the filename from a HANDLE. It is
not portably possible to do this on Unix, so the filename which was
opened by the stdlib/header.c is instead appended to the environment
variable.

Add comments on the handling of blank env vars

Clarify in various places the behaviour of reading an environment
variable which is "Set But Null" (i.e. equal to the empty string as
opposed to unset)

Ignore empty TMPDIR in the Filename module

For Unix, the Filename module now treats TMPDIR being set to the
empty string, as if it were not set at all (which causes it to use /tmp
instead).

Ignore empty TMPDIR in ocamlyacc

If TMPDIR is set to the empty string, the Unix build of ocamlyacc now
defaults to /tmp (as it would if TMPDIR were not set at all).

The Windows default for when TMPDIR is not set is alredy the current
directory, so no change is required.

Propagate non-empty tmpdir in ocamlyacc

By making tmpdir explicitly "." in the rare corner-case of TMPDIR being
set to the empty string on Windows, it becomes unnecessary to keep
checking whether tmpdir is zero-length.

Ignore CAML_DEBUG_FILE if it's "Set But Null"

Ignore OCAMLPROF_DUMP if it's "Set But Null"

Use non-raising Sys.getenv_opt in win32unix

Use the non-raising Sys.getenv_opt internally in the Windows
implementation of the Unix module. In passing, treat the highly unlikely
corner case of COMSPEC being "Set But Null" as if COMSPEC were not set.

Ignore empty strings in Compmisc.set_from_env

Previously, invocations such as

OCAML_COLOR= ocamlopt

emitted warning 46 (bad-env-variable) which is not particularly helpful.
At present, Compmisc.set_from_env is used to implement OCAML_COLOR and
OCAML_ERROR_STYLE, neither of which attached significance to the empty
string. Compmisc.set_from_env is there changed to explictly ignore the
environment variable value if it is "".

Ignore empty environment variables in ocamltest

Most uses in ocamltest were via its safe_getenv function which already
made unset and empty equivalent. This generalises the underlying
getenv_with_default_value function always to return the default value if
the variable is _either_ unset or set to the empty string.

Ignore empty MAKE variable in ocamltest

Treat OCAML_BINANNOT_WITHENV as unset when empty

This environment is intended to be used in the context of
OCAML_BINANNOT_WITHENV=1 to enable it, so treat OCAML_BINANNOT_WITHENV=
as if it weren't set at all.

Add some limited information about CAMLSIGPIPE

Ignore empty OCAML_RUNTIME_EVENTS_ variables

The handling of OCAML_RUNTIME_EVENTS_DIR was incorrect if the value as
"Set But Null" and the intention in the manual for
OCAML_RUNTIME_EVENTS_START and OCAML_RUNTIME_EVENTS_PRESERVE is clearly
that they should be set to non-empty values in order to trigger the
required effect.

All three variables are now ignored if they are set, but to an empty
string.

Harden processing of SOURCE_DATE_EPOCH in ocamldoc

Previously, running:

SOURCE_DATE_EPOCH= ocamldoc

resulted in an uncaught Failure "float_of_string" exception. The
processing of SOURCE_DATE_EPOCH is firstly hardened to cope with parsing
errors and then a one-time warning is displayed the first time it's
actually used (at present it's only required in Odoc_man).

Ignore blank OCAMLRUNPARAM, OCAMLLIB and CAMLLIB

Previously, if OCAMLRUNPARAM was "Set But Null", CAMLRUNPARAM was
completely ignored. Similarly, a "Set But Null" value for OCAMLLIB
caused CAMLLIB and subsequently the default location of the Standard
Library to be ignored. Especially for OCAMLLIB/CAMLLIB, this behaviour
is counter-intuitive, as it's highly unlikely to be useful.

Now, if OCAMLLIB is set, but to the empty string, then CAMLLIB is
checked and, more importantly, if it is either not set or also set to
the empty string then the default location of the Standard Library is
still used. For consistency, if OCAMLRUNPARAM is set, but to the empty string,
then CAMLRUNPARAM is read.

Ignore empty components in PATH-like things

POSIX recognises empty components in a PATH-like variable as meaning "."
(the current directory). This is reflected in the processing of
OCAMLTOP_INCLUDE_PATH, CAML_LD_LIBRARY_PATH and ld.conf where either a
blank component or a blank line is interpreted as "."

Somewhat confusingly, this processing is applied inconsistently between
Unix and Windows (it's confusing given that Windows more readily
includes the current working directory by default in PATH searches).

It also has the side-effect that a "Set But Null" environment variable
is interpreted as "." which counter-intuitively makes
CAML_LD_LIBRARY_PATH= ocamlrun add the current working directory to the
search path.

Blank lines and empty components of both OCAMLTOP_INCLUDE_PATH and
CAML_LD_LIBRARY_PATH are now ignored. The current working directory can
still be explicitly included, of course, by adding a "." entry/line
where required.

Add %shared_libraries primitive

Exposes the value of SUPPORT_DYNAMIC_LINKING.

Bootstrap

Improve the "dynamic loading not supported" error

It is possible, especially when using Dynlink, to end up in the
situation where a bytecode runtime which doesn't support dynamic loading
is asked to load support DLLs (e.g. a bytecode image with a DLLS
section, or a cma archive passed to the toplevel/Dynlink which has a
non-empty lib_dllibs list).

Previously, the error message would refer to the name of the first DLL
being loaded and simply state that dynamic loading is not supported. The
confusing part is that typically this would refer to a DLL which is not
on the system.

Now, the bytecode linker only writes DLLS and DLPT when there are
entries to write in them, and the runtime, toplevel and Dynlink provide
a direct explanation that dynamic loading is needed, but is not
available. In particular, the error now refers to the file which is
being loaded (i.e. the bytecode executable or the .cma file) rather than
a .so file which doesn't exist.

Free tables after handing off to Dynlink

In the debug runtime, caml_prim_name_table remains for the lifetime of
the program, as it's used by instrtrace.c, but in normal operation, once
the list of primitives has been handed over to Dynlink, it's no longer
required. In the normal runtime, it's now freed after this handover.

In passing, strings themselves are no longer duplicated, as the code
path is a good deal simpler than it used to be, and the bytecode section
itself can reliably be used as the underlying buffer for
caml_prim_name_table.

caml_shared_libs_path is only kept at all to be handed over to Dynlink.
It, along with the two underlying buffers for CAML_LD_LIBRARY_PATH and
ld.conf are freed after the call.

Move print_magic and print_config out of caml_params

They are only used by the bytecode runtime and can be made static to
startup_byt.

Preserve option R in caml_runtime_parameters

The setting for R was previous omitted in Sys.runtime_parameters, since
it was only processed directly by the Hashtbl module and not stored in
the runtime. Option R is now processed in caml_parase_ocamlrunparam and
stored to be accessed and updated via new primitives for the Hashtbl
module.

Co-authored-by: David Allsopp <david.allsopp@metastack.com>

Swap the V and v in caml_runtime_parameters

Consistency - options displayed in alphabetical order with the uppercase
letter appearing before the lowercase letter

Add -set-runtime-default to the compilers

When linking an executable, allows to set default to OCAMLRUNPARAM
values. This new OCAMLRUNPARAM string is accessible using the
"caml_executable_ocamlrunparam" symbol or is embedded in a bytecode
section.

Co-authored-by: David Allsopp <david.allsopp@metastack.com>

Test -set-runtime-default in test-in-prefix

The test programs in the run after the prefix has been renamed are
compiled with `-set-runtime-default R`, and the test program verifies
that Hashtbl.is_randomized returns the expected value.

Re-order initialisations in bytecode

In bytecode startup, defer allocating memory until after the bytecode
image has been loaded as far as possible.

Support c=1 mode in ocamlrun

The runtime's pooling mode has a slight Catch-22 problem for ocamlrun
when enabled using -set-runtime-default. Opening the bytecode file and
reading the ORUN section requires the memory subsystem.

In this revised version, caml_main in bytecode is particularly careful
to track exactly what will have been allocated prior to reading the ORUN
section and if ORUN requires the system to start pooling mode, the
runtime now takes temporary malloc'd copies of everything which has been
made so far so that it can be safely copied with a caml_stat_alloc
_after_ pooling mode has been enabled.

Fix C library options for win32unix

-lws2_32 and -ladvapi32 are already supplied by default, so they don't
need to be in unix.cma/unix.cmxa. However, they do need to be passed
when building unix.cmxs, and they were previously acquired via
unix.cmxa. Tweak the way LDOPTS is used in Makefile.otherlibs.common
(which now is only used for the unix library) so that it's correctly
passed to both ocamlopt and ocamlmklib.

Build and install threads.cmxs

Crucially, the corrects the flags used for creating a DLL on Windows,
allowing threads.cmxs to be loaded in ocamlnat.

Fix inclusion of libraries when partial linking

ld -r (certainly in GNU binutils) has an empty search path - co-opt the
MSVC search code and always resolve libraries when partial linking,
except this time _ignore_ the ones which are missing. This seems to fit
the rest of -output-complete-obj, given that the _standard_ C libraries
are also omitted (-lm, -lpthread, etc.)

Use entrypoint flexdll branch

Fixes loading unix.cmxs in Cygwin64

Stop installing and documenting config_main, etc.

Config_main and Config_boot are built to ensure in the build that
utils/config.generated.ml.in and utils/config.fixed.ml are kept in sync
(so that the next bootstrap doesn't unexpectedly break). However,
because these files were generated in the utils directory, they were
picked up both by the install recipe and also when generating API
documentation.

It's slightly hairy to remove the wildcards and use filter, because we
can easily end up with command lines which are too long (even on Unix),
so instead these two modules are now generated in utils/config/

Use clang-cl for flexdll support objects

Two minor clean-ups in the in-prefix-tests

Dead code in the Makefile and the less-trodden path in
Test_ld_conf.ensure_dir contained an obvious incorrect function call...

Add caml_output_value_with_compat primitive

Alternate version of caml_output_value which returns a boolean
indicating if the result was 32-bit compatible and would have succeeded
if Compat_32 had been included in the flags.

Split Meta into two

All the functions in Meta are now only required by the toplevel, however
two of them are still quite tangled up with Symtable. Begin the process
of disentanglement by moving those two functions to Symtable and the
remaining ones directly to the bytecode toplevel (Dynlink already has
its own implementations).

Omit CRCS if caml_reify_bytecode isn't used

Bytecode images (including for -output-obj) now only include the CRCS
section if the image actually needs dynamic loading (which is identified
by the use of the caml_reify_bytecode primitive which is only used by
the toplevel and dynlink).

Eliminate post-processing of bootstrap artefact

In order to be repeatable, the coreboot cycle routinely has to relink
both boot artefacts with a fixed configuration. It's not therefore much
more of a stretch to link those artefacts with the required flags to
suppress both the header (and RNTM section, if applicable) and debugging
information.

Combined with the previous change to suppress CRCS when the image
doesn't use dynamic loading, the coreboot cycle can be accomplished
without having to post-process the artefacts with stripdebug.

Fold-back into the test