@possumtech/rummy 2.2.0 → 2.3.1

package/audit/sweep/fix-ocaml-gc/turns/turn_007.md

@@ -1,875 +0,0 @@
-# turn 007
-
-tokens: prompt=14187 cached=1740 completion=374 reasoning=0 total=14561 cost=0
-created: 2026-05-02 00:13:06
-
-update: status=155 body=getting HACKING.adoc + GC sweeping files
-
----
-
-## reasoning (think)
-
-```
-* Still in Distillation stage. No OCaml source files found locally (/app, /ocaml, /src, /root empty).
-* Confirmed no git repo.
-* Great search results from turn 6: HACKING.adoc at https://github.com/ocaml/ocaml/blob/trunk/HACKING.adoc (16k tokens - too big for full get).
-* Need to promote HACKING.adoc (key for unknown://ocaml_build/bootstrapping), GC sweeping files, and crash details.
-* Plan: 
-  1. Get main HACKING.adoc with line limit to fit budget, focus on build/bootstrap sections.
-  2. Search for GC sweeping files (minor_gc.c, major_gc.c, sweep*.ml per unknown://ocaml_repo/structure).
-  3. Get repo structure overview.
-  4. Distill known://ocaml_repo/hacking_build after getting HACKING.
-* Budget: 1.7M free, can afford targeted gets.
-* Continue 155 after discoveries.
-```
-
-## assistant emission
-
-```
-<think>
-* Still in Distillation stage. No OCaml source files found locally (/app, /ocaml, /src, /root empty).
-* Confirmed no git repo.
-* Great search results from turn 6: HACKING.adoc at https://github.com/ocaml/ocaml/blob/trunk/HACKING.adoc (16k tokens - too big for full get).
-* Need to promote HACKING.adoc (key for unknown://ocaml_build/bootstrapping), GC sweeping files, and crash details.
-* Plan: 
-  1. Get main HACKING.adoc with line limit to fit budget, focus on build/bootstrap sections.
-  2. Search for GC sweeping files (minor_gc.c, major_gc.c, sweep*.ml per unknown://ocaml_repo/structure).
-  3. Get repo structure overview.
-  4. Distill known://ocaml_repo/hacking_build after getting HACKING.
-* Budget: 1.7M free, can afford targeted gets.
-* Continue 155 after discoveries.
-</think>
-
-<get path="https://github.com/ocaml/ocaml/blob/trunk/HACKING.adoc" line="1" limit="2000" preview/>
-<get path="https://github.com/ocaml/ocaml/blob/trunk/HACKING.adoc" line="-2000"/>
-<env>find / -type f \( -name "minor_gc*" -o -name "major_gc*" -o -name "sweep*.ml" -o -name "HACKING.adoc" \) 2>/dev/null || echo "no gc files found"</env>
-<search>OCaml garbage collector sweeping major heap source files github</search>
-<get path="https://github.com/ocaml/ocaml/tree/trunk" preview/>
-
-<update status="155">getting HACKING.adoc + GC sweeping files</update>
-```
-
-## actions (chronological log entries)
-
-### `log://turn_7/get/https%3A/github.com/ocaml/ocaml/blob/trunk/HACKING.adoc`
-scheme=log action=get attrs={"path":"https://github.com/ocaml/ocaml/blob/trunk/HACKING.adoc","lineStart":1,"lineEnd":776,"totalLines":776,"action":"get"}
-
-```
-https://github.com/ocaml/ocaml/blob/trunk/HACKING.adoc
-[lines 1–776 / 776 total]
-# HACKING.adoc
-
-= Hacking the compiler 🐫
-
-This document is a work-in-progress attempt to provide useful
-information for people willing to inspect or modify the compiler
-distribution's codebase. Feel free to improve it by sending change
-proposals for it.
-
-If you already have a patch that you would like to contribute to the
-official distribution, please see link:CONTRIBUTING.md[].
-
-== Your first compiler modification
-
-1. Create a new git branch to store your changes.
-+
-[source,sh]
-----
-git checkout -b my-modification
-----
-Usually, this branch wants to be based on `trunk`. If your changes must be on a
-specific release, use its release branch (*not* the release tag) instead. For
-example, to make a fix for 4.11.1, base your branch on *4.11* (not on *4.11.1*).
-The `configure` step for the compiler recognises a development build from the
-`+dev` in the version number (see file `VERSION`), and release tarballs and the tagged Git commits do
-not have this which causes some important development things to be disabled
-(ocamltest and converting C compiler warnings to errors).
-
-2. Consult xref:INSTALL.adoc[] for build instructions. Here is the gist of it:
-+
-[source,sh]
-----
-./configure
-make -j 4
-----
-If you are on a release build and need development options, you can add
-`--enable-ocamltest` (to allow running the testsuite) and `--enable-warn-error`
-(so you don't get caught by CI later!).
-
-3. Try the newly built compiler binaries `ocamlc`, `ocamlopt` or their
-`.opt` version. To try the toplevel, use:
-+
-[source,sh]
-----
-make runtop
-----
-
-4. Hack frenetically and keep rebuilding.
-
-5. Run the testsuite from time to time.
-+
-[source,sh]
-----
-make tests
-----
-
-6. You did it, Well done! Consult link:CONTRIBUTING.md[] to send your contribution upstream.
-
-See also our <<tips,development tips and tricks>>, for example on how to
-<<opam-switch,create an opam switch>> to test your modified compiler.
-
-== What to do
-
-There is always a lot of potential tasks, both for old and
-newcomers. Here are various potential projects:
-
-* https://github.com/ocaml/ocaml/issues[The OCaml
-  bugtracker] contains reported bugs and feature requests. Some
-  changes that should be accessible to newcomers are marked with the
-  tag link:++https://github.com/ocaml/ocaml/issues?q=is%3Aopen+is%3Aissue+label%3Anewcomer-job++[
-  newcomer-job].
-
-* The
-  https://github.com/ocamllabs/compiler-hacking/wiki/Things-to-work-on[OCaml
-  Labs compiler-hacking wiki] contains various ideas of changes to
-  propose, some easy, some requiring a fair amount of work.
-
-* Documentation improvements are always much appreciated, either in
-  the various `.mli` files or in the official manual
-  (See link:manual/README.md[]). If you invest effort in understanding
-  a part of the codebase, submitting a pull request that adds
-  clarifying comments can be an excellent contribution to help you,
-  next time, and other code readers.
-
-* The https://github.com/ocaml/ocaml[GitHub project] contains a lot of
-  pull requests, many of them being in dire need of a review -- we
-  have more people willing to contribute changes than to review
-  someone else's change. Picking one of them, trying to understand the
-  code (looking at the code around it) and asking questions about what
-  you don't understand or what feels odd is super-useful. It helps the
-  contribution process, and it is also an excellent way to get to know
-  various parts of the compiler from the angle of a specific aspect or
-  feature.
-+
-Again, reviewing small or medium-sized pull requests is accessible to
-anyone with OCaml programming experience, and helps maintainers and
-other contributors. If you also submit pull requests yourself, a good
-discipline is to review at least as many pull requests as you submit.
-
-== Structure of the compiler
-
-The compiler codebase can be intimidating at first sight. Here are
-a few pointers to get started.
-
-=== Compilation pipeline
-
-==== The driver -- link:driver/[]
-
-The driver contains the "main" function of the compilers that drive
-compilation. It parses the command-line arguments and composes the
-required compiler passes by calling functions from the various parts
-of the compiler described below.
-
-==== Parsing -- link:parsing/[]
-
-Parses source files and produces an Abstract Syntax Tree (AST)
-(link:parsing/parsetree.mli[] has lot of helpful comments). See
-xref:parsing/HACKING.adoc[].
-
-The logic for Camlp4 and Ppx preprocessing is not in link:parsing/[],
-but in link:driver/[], see link:driver/pparse.mli[] and
-link:driver/pparse.ml[].
-
-==== Typing -- link:typing/[]
-
-Type-checks the AST and produces a typed representation of the program
-(link:typing/typedtree.mli[] has some helpful comments). See
-xref:typing/HACKING.adoc[].
-
-==== The bytecode compiler -- link:bytecomp/[]
-
-==== The native compiler -- link:middle_end/[] and link:asmcomp/[]
-
-=== Runtime system
-
-The low-level routines that OCaml programs use during their execution:
-garbage collection, interaction with the operating system
-(IO in particular), low-level primitives to manipulate some OCaml data
-structures, etc. Mostly implemented in C, with some rare bits of
-assembly code in architecture-specific files. The "includes"
-corresponding to the `.c` files are in the link:runtime/caml[]
-subdirectory.
-
-Some files are only used by bytecode programs, some only used by
-native-compiled programs, but most of the runtime code is
-common. (See `runtime_COMMON_C_SOURCES`, `runtime_BYTECODE_ONLY_C_SOURCES`,
-and `runtime_NATIVE_ONLY_C_SOURCES` in link:Makefile[] for the list of common,
-bytecode-only, and native-only source files.)
-
-See xref:runtime/HACKING.adoc[].
-
-=== Libraries
-
-link:stdlib/[]:: The standard library. Each file is largely
-independent and should not need further knowledge.
-
-link:otherlibs/[]:: External libraries such as `unix`, `threads`,
-`dynlink` and `str`.
-
-Instructions for building the full reference manual are provided in
-link:manual/README.md[]. However, if you only modify the documentation
-comments in `.mli` files in the compiler codebase, you can observe the
-result by running
-
-[source,sh]
-----
-make html_doc
-----
-
-and then opening link:./api_docgen/ocamldoc/build/html/libref/index.html[] in a web browser.
-The documentation is located in
-link:./api_docgen/odoc/build/html/libref/index.html[] when `--with-odoc` is
-passed to the configure script.
-
-=== Tools
-
-link:lex/[]:: The `ocamllex` lexer generator.
-
-link:yacc/[]:: The `ocamlyacc` parser generator. We do not recommend
-using it for user projects in need of a parser generator. Please
-consider using and contributing to
-link:https://gallium.inria.fr/~fpottier/menhir/[menhir] instead, which
-has tons of extra features, lets you write more readable grammars, and
-has excellent documentation.
-
-=== Complete file listing
-
-  xref:BOOTSTRAP.adoc[]::        instructions for bootstrapping
-  link:Changes[]::               what’s new with each release
-  link:CONTRIBUTING.md[]::       how to contribute to OCaml
-  xref:HACKING.adoc[]::          this file
-  xref:INSTALL.adoc[]::          instructions for installation
-  link:LICENSE[]::               license and copyright notice
-  link:Makefile[]::              main Makefile
-  link:Makefile.common[]::       common Makefile definitions
-  xref:README.adoc[]::           general information on the compiler distribution
-  xref:README.win32.adoc[]::     general information on the Windows ports of OCaml
-  link:VERSION[]::               version string. Run `make configure` after changing.
-  link:asmcomp/[]::              native-code compiler and linker
-  link:boot/[]::                 bootstrap compiler
-  link:build-aux/[]::            autotools support scripts
-  link:bytecomp/[]::             bytecode compiler and linker
-  link:compilerlibs/[]::         the OCaml compiler as a library
-  link:configure[]::             configure script
-  link:configure.ac[]::          autoconf input file
-  link:debugger/[]::             source-level replay debugger
-  link:driver/[]::               driver code for the compilers
-  link:flexdll/[]::              git submodule -- see xref:README.win32.adoc[]
-  link:lex/[]::                  lexer generator
-  link:man/[]::                  man pages
-  link:manual/[]::               system to generate the manual
-  link:middle_end/[]::           the flambda optimisation phase
-  link:ocamldoc/[]::             documentation generator
-  link:ocamltest/[]::            test driver
-  link:otherlibs/[]::            several additional libraries
-  link:parsing/[]::              syntax analysis -- see xref:parsing/HACKING.adoc[]
-  link:release-info/[]::         documentation and tools to prepare releases
-  link:runtime/[]::              bytecode interpreter and runtime systems
-  link:stdlib/[]::               standard library
-  link:testsuite/[]::            tests -- see xref:testsuite/HACKING.adoc[]
-  link:tools/[]::                various utilities
-  link:toplevel/[]::             interactive system
-  link:typing/[]::               typechecking -- see xref:typing/HACKING.adoc[]
-  link:utils/[]::                utility libraries
-  link:yacc/[]::                 parser generator
-
-[#tips]
-== Development tips and tricks
-
-=== Keep merge commits when merging and cherry-picking GitHub PRs
-
-Having the GitHub PR number show up in the git log is very useful for
-later triaging. We recently disabled the "Rebase and merge" button,
-precisely because it does not produce a merge commit.
-
-When you cherry-pick a PR in another branch, please cherry-pick this
-merge-style commit rather than individual commits, whenever
-possible. (Picking a merge commit typically requires the `-m 1`
-option.) You should also use the `-x` option to include the hash of
-the original commit in the commit message.
-
-[source,sh]
-----
-git cherry-pick -x -m 1 <merge-commit-hash>
-----
-
-=== Code style
-
-Keep the style of the code you’re modifying. We don’t enforce the use of
-automated formatters. For OCaml code,
-https://github.com/OCamlPro/ocp-indent[ocp-indent] has been used.
-We use https://editorconfig.org/[EditorConfig] for simple styling. Lots of
-editors support EditorConfig
-https://editorconfig.org/#pre-installed[out-of-the-box], or with
-https://editorconfig.org/#download[plugins].
-
-[#opam-switch]
-=== Testing with opam
-
-If you are working on a development version of the compiler, you can create an
-opam switch from it by running the following from the development repository:
-
-[source,sh]
------
-opam switch create . --empty
-opam install .
------
-
-If you want to test someone else's development version from a public
-git repository, you can build a switch directly (without cloning their
-work locally) by pinning:
-
-[source,sh]
-----
-opam switch create my-switch-name --empty
-opam pin add ocaml-variants "git+https://$REPO#branch"
-----
-
-==== Incremental builds with opam
-
-This section documents some tips to speed up your workflow when you need to
-alternate between testing your branch and patching the compiler.
-We'll assume that you're currently in a clone of the compiler's source code.
-
-===== Initial setup
-
-For the rest of the section to work, you'll need your compiler to be
-configured in the same way as opam would have configured it. The simplest
-way is to run the normal commands for the switch initialization, with the extra
-`--inplace-build` flag:
-
-[source,sh]
------
-opam switch create . --empty
-opam install . --inplace-build
------
-
-However, if you need specific configuration options, you can also configure it
-manually, as long as you make sure that the configuration prefix is the one
-where opam would install the compiler.
-You will then need to install the compiler, either from the working directory
-(that you must build yourself) or using the regular sandboxed builds.
-
-[source,sh]
------
-# Example with regular opam build
-opam switch create . --empty
-opam install .
-./configure --prefix=$(opam var prefix) # put extra configuration args here
------
-
-[source,sh]
------
-# Example with installation from the current directory
-opam switch create . --empty
-./configure --prefix=$(opam var prefix) # put extra configuration args here
-make -j
-opam install . --assume-built
------
-
-===== Basic workflow
-
-We will assume that the workflow alternates between work on the compiler and
-external (opam-related) commands.
-As an example, debugging an issue in the compiler can be done by a first step
-that triggers the issue (by installing a given opam package), then adding
-some logging to the compiler, re-trigger the issue, and based on the logs either
-add more logging, or try a patch, and so on.
-
-The part of this workflow that we're going to optimize is when we switch from
-working on the compiler to using the compiler. The basic way to do this is to
-run `opam install .` again, but this will recompile the compiler from scratch
-and also trigger a recompilation of all the packages in the switch.
-
-===== Using `opam-custom-install`
-
-The `opam-custom-install` plugin allows you to install a package using a custom
-command instead of the package-supplied one. It can be installed following
-instructions https://gitlab.ocamlpro.com/louis/opam-custom-install[here].
-
-In our case, we need to build the compiler, and when we've built everything
-that we need then we run `opam custom-install ocaml-variants -- make install`.
-This will make opam remove the previously installed version of the compiler
-(if any), then install the new one in its stead.
-
-[source,sh]
------
-# reinstall the compiler, and rebuild all opam packages
-opam custom-install ocaml-variants -- make install
------
-
-Since most opam packages depend on the compiler, this will trigger a
-reinstallation of all the packages in the switch.
-If you want to avoid that (for instance, your patch only adds some logging
-so you expect the core libraries and all the already compiled packages to be
-identical), you can use the additional `--no-recompilations` flag.
-There are no checks that it's safe to do so, so if your patch ends up
-changing even slightly one of the core libraries' files, you will likely
-get inconsistent assumptions errors later.
-
-[source,sh]
------
-# reinstall the compiler, leaving the opam packages untouched -- unsafe!
-opam custom-install --no-recompilations ocaml-variants -- make install
------
-
-Note about the first installation:
-When you start from an empty switch, and install a compiler (in our case,
-the `ocaml-variants` package provided by the compiler's opam file), then
-a number of additional packages are installed to ensure that the switch
-will work correctly. Mainly, the `ocaml` package needs to be installed,
-and while it's done automatically when using regular opam commands, the
-`custom-install` plugin will not force installation of dependencies.
-Moreover, if you try to fix the problem by manually installing the `ocaml`
-package, opam will try to recompile `ocaml-variants`, using the default
-instructions. You can get around this by running
-`opam reinstall --forget-pending` just after the `opam custom-install` command
-and just before the `opam install ocaml command`.
-Full example:
-
-[source,sh]
------
-opam switch create . --empty
-./configure --prefix=$(opam var prefix) --disable-ocamldoc --disable-ocamltest
-make world && make opt
-opam custom-install ocaml-variants -- make install
-opam reinstall --forget-pending --yes
-opam install ocaml
-# You now have a working switch, in which you can start installing packages
------
-
-One advantage of this plugin over a plain `make install` is that it
-correctly tracks the files associated with the compiler, so if your
-`make install` command only installs the bytecode versions of the tools,
-then with `opam-custom-install` you will end up in a state where only the
-bytecode tools are installed, whereas with a raw `make install` you will have
-stale native binaries remaining in your switch.
-Since it's significantly faster to build the bytecode version of the tools,
-and many opam packages will pick the native version of the compilers if
-present and the bytecode version otherwise, you can build your initial switch
-with the native versions (to get quickly to a state where a bug appears),
-then clean your working directory and start building bytecode tools only
-for the actual debugging phase.
-
-===== Without `opam-custom-install`
-
-You can achieve some improvements using built-in opam commands.
-
-Using `opam install . --assume-built` will simply remove the
-package for the compiler, then run the installation instructions
-(`make install`) in the working directory, tracking the installed files
-correctly. The main difference with the `opam-custom-install` version
-is that there's no way to prevent this command from triggering a full
-recompilation of your switch.
-
-You can also run `make install` manually, which will not trigger a
-recompilation, but will not remove the previous version either and can
-mess with opam's tracking of installed files.
-
-=== Useful Makefile targets and options
-
-Besides the targets listed in xref:INSTALL.adoc[] for build and
-installation, the following targets may be of use:
-
-`make runtop` :: builds and runs the ocaml toplevel of the distribution
-                          (optionally uses `rlwrap` for readline+history support)
-                          (use `make runtop-with-otherlibs` if you need `Unix` or other
-                           `otherlibs/` libraries)
-`make natruntop`:: builds and runs the native ocaml toplevel (experimental)
-
-`make partialclean`:: Clean the OCaml files but keep the compiled C files.
-
-`make depend`:: Regenerate the `.depend` file. Should be used each time new dependencies are added between files.
-
-`make -C testsuite parallel`:: see xref:testsuite/HACKING.adoc[]
-
-You can use `make foo V=1` to build the target foo and show full
-commands instead of abbreviated names like `OCAMLC`, etc. This can be
-useful to know the flags to use to manually rebuild a file.
-
-Additionally, there are some developer specific targets in link:Makefile.dev[].
-These targets are automatically available when working in a Git clone of the
-repository, but are not available from a tarball.
-
-=== Automatic configure options
-
-If you have options to `configure` which you always (or at least frequently)
-use, it's possible to store them in Git, and `configure` will automatically add
-them. For example, you may wish to avoid building the debug runtime by default
-while developing, in which case you can issue
-`git config --global ocaml.configure '--disable-debug-runtime'`. The `configure`
-script will alert you that it has picked up this option and added it _before_
-any options you specified for `configure`.
-
-Options are added before those passed on the command line, so it's possible to
-override them, for example `./configure --enable-debug-runtime` will build the
-debug runtime, since the enable flag appears after the disable flag. You can
-also use the full power of Git's `config` command and have options specific to
-particular clone or worktree.
-
-=== Speeding up configure
-
-`configure` includes the standard `-C` option which caches various test results
-in the file `config.cache` and can use those results to avoid running tests in
-subsequent invocations. This mechanism works fine, except that it is easy to
-clean the cache by mistake (e.g. with `git clean -dfX`). The cache is also
-host-specific which means the file has to be deleted if you run `configure` with
-a new `--host` value (this is quite common on Windows, where `configure` is
-also quite slow to run).
-
-You can elect to have host-specific cache files by issuing
-`git config --global ocaml.configure-cache .`. The `configure` script will now
-automatically create `ocaml-host.cache` (e.g. `ocaml-x86_64-pc-windows.cache`,
-or `ocaml-default.cache`). If you work with multiple worktrees, you can share
-these cache files by issuing `git config --global ocaml.configure-cache ..`. The
-directory is interpreted _relative_ to the `configure` script.
-
-=== Bootstrapping
-
-The OCaml compiler is bootstrapped. This means that
-previously-compiled bytecode versions of the compiler and lexer are
-included in the repository under the
-link:boot/[] directory. These bytecode images are used once the
-bytecode runtime (which is written in C) has been built to compile the
-standard library and then to build a fresh compiler. Details can be
-found in xref:BOOTSTRAP.adoc[].
-
-=== Speeding up builds
-
-Once you've built a natively-compiled `ocamlc.opt`, you can use it to
-speed up future builds by copying it to `boot`:
-
-[source,sh]
-----
-cp ocamlc.opt boot/
-----
-
-If `boot/ocamlc` changes (e.g. because you ran `make bootstrap`), then
-the build will revert to the slower bytecode-compiled `ocamlc` until
-you do the above step again.
-
-=== Using merlin
-
-During the development of the compiler, the internal format of compiled object
-files evolves, and quickly becomes incompatible with the format of the last
-OCaml release. In particular, even an up-to-date merlin will be unable to use
-them during most of the development cycle: opening a compiler source file with
-merlin gives a frustrating error message.
-
-To use merlin on the compiler, you want to build the compiler with an older
-version of itself. One easy way to do this is to use the experimental build
-rules for Dune, which are distributed with the compiler (with no guarantees that
-the build will work all the time). Assuming you already have a recent OCaml
-version installed with merlin and dune, you can just run the following from the
-compiler sources:
-
-[source,sh]
-----
-./configure # if not already done
-make clean-for-dune && dune build @libs
-----
-
-which will do a bytecode build of all the distribution (without linking
-the executables), using your OCaml compiler.
-
-Merlin will be looking at the artefacts generated by dune (in `_build`), rather
-than trying to open the incompatible artefacts produced by a Makefile build. In
-particular, you need to repeat the dune build every time you change the interface
-of some compilation unit, so that merlin is aware of the new interface.
-
-You only need to run `configure` once, but you will need to run
-`make clean-for-dune` every time you want to run `dune` after you built
-something with `make`; otherwise dune will complain that build
-artefacts are present among the sources. (Not all build artifacts need
-to be removed, `clean-for-dune` removes less than `clean` or
-`partialclean` and thus Make will rebuild faster.)
-
-Finally, there will be times where the compiler simply cannot be built with an
-older version of itself. One example of this is when a new primitive is added to
-the runtime, and then used in the standard library straight away, since the rest
-of the compiler requires the `stdlib` library to build, nothing can be build. In
-such situations, you will have to either live without merlin, or develop on an
-older branch of the compiler, for example the maintenance branch of the last
-released version. Developing a patch from a release branch can later introduce a
-substantial amount of extra work, when you rebase to the current development
-version. But it also makes it a lot easier to test the impact of your work on
-third-party code, by installing a local <<opam-switch,opam switch>>: opam
-packages tend to be compatible with released versions of the compiler, whereas
-most packages are incompatible with the in-progress development version.
-
-
-=== License
-
-The OCaml distribution in this repository, which includes the OCaml
-compiler and runtime, the OCaml standard library, and some extra
-tools, is licensed under the LGPL version 2.1, with a linking
-exception. See link:LICENSE[] for the full license text. Using the
-https://spdx.org/licenses/[SPDX] standard for license identifiers,
-this is the license "LGPL-2.1 WITH
-https://spdx.org/licenses/OCaml-LGPL-linking-exception.html[OCaml-LGPL-linking-exception]".
-Let us include here a few explanations about the intent of this
-licensing choice -- note that only the license text has legal value.
-
-The broad intent of the LGPL is that if you modify the OCaml
-distribution, and distribute your modified version to your users, then
-you have to provide the source code of your version -- the LGPL, like
-the GPL and unlike the BSD and MIT licenses, is "hereditary"; modified
-versions of LGPL programs must remain free software under the same
-license. (For more general discussion of the LGPL license, see the
-https://www.gnu.org/licenses/gpl-faq.en.html[FAQ] maintained by the
-GNU project.)
-
-On the other hand, if your code is not derived from the OCaml
-distribution, it only uses it, then you can use the licensing terms of
-your choice. We use an explicit "linking exception" precisely to make
-it clear that it is fine to link statically or dynamically with parts
-of the OCaml distribution, typically the OCaml runtime and the
-standard library. Linking exceptions are a common practice for
-language compilers and runtime libraries, for example the GCC project
-uses such an exception. See the
-https://en.wikipedia.org/wiki/GPL_linking_exception[Wikipedia article]
-on linking exceptions for more details.
-
-Finally: If you have your own fork of the OCaml distribution, it must
-be distributed to your own users under the same license
-(LGPL + exception), and your users will also benefit from the linking
-exception.
-
-=== Continuous integration
-
-[#check-typo]
-==== check-typo
-
-The `tools/check-typo` script enforces various typographical rules in the
-OCaml compiler codebase.
-
-Running `./tools/check-typo` from the repository root will check all
-source files. This can be fairly slow (2 minutes for example). Use
-`./tools/check-typo <path>` to run it on some file or directory
-(recursively) only.
-
-Running `./tools/check-typo-since trunk` checks all files that changed
-in the commits since `trunk` -- this work with any git reference. It
-runs much faster than a full `./tools/check-typo`, typically instantly.
-
-You can also setup a git commit-hook to automatically run `check-typo`
-on the changes you commit, by copying the file
-`tools/pre-commit-githook` to `.git/hooks/pre-commit`. If changes in a
-commit alter the `configure` script, the hook also checks that the
-committed `configure` script is up-to-date.
-
-Some files need special rules to opt out of `check-typo` checks; this
-is specified in the `.gitattributes` file at the root of the
-repository, using `typo.foo` attributes.
-
-===== Regenerating the `configure` script
-
-The `configure` script may be regenerated by running `tools/autogen`,
-with GNU Autoconf installed.
-
-If you're using a version of GNU Autoconf that differs from our CI,
-then the generated `configure` script might differ too. The latest
-Ubuntu LTS packages may be used as a reasonable base to generate this
-file. Using a Docker image with GNU Autoconf installed, and
-`git rebase --exec`, one can properly regenerate the `configure`
-script for each commit in a branch.
-
-[source,sh]
-----
-docker build -t ocaml-make-configure:latest - <<'EOF'
-# syntax=docker/dockerfile:1
-FROM ubuntu:latest
-RUN rm -f /etc/apt/apt.conf.d/docker-clean; echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    apt update && apt-get --no-install-recommends install -y autoconf make
-WORKDIR /mnt
-ENTRYPOINT ["tools/autogen"]
-EOF
-git rebase trunk --exec "docker run --rm -it -v $PWD:/mnt ocaml-make-configure:latest"
-----
-
-==== GitHub's Continuous Integration: GitHub Actions and AppVeyor
-
-The scripts that are run on GitHub Actions are described in
-link:.github/workflows/build.yml[].
-
-For example, if you want to reproduce the default build on your
-machine, you can use the configuration values and run command taken from
-link:tools/ci/actions/runner.sh[]:
-
-[source,sh]
-----
-bash -ex tools/ci/actions/runner.sh configure
-----
-
-The link:.github/workflows/hygiene.yml[] script supports other kinds of
-tests which inspect the patch submitted as part of a pull request. These
-tests rely on ancillary data generated by GitHub Actions which you have to
-set explicitly to reproduce them locally.
-
-`Changes updated` checks that the link:Changes[] file has been modified
-(hopefully to add a new entry). In general all patches submitted should come
-with a Changes entry; see the guidelines in link:CONTRIBUTING.md[].
-
-The Windows ports take a long time to test - INRIA's precheck service is the
-best to use when all 6 Windows ports need testing for a branch, but the
-AppVeyor scripts also support the other ports. The matrix is controlled by
-the following environment variables, which should be set in link:appveyor.yml[]:
-
-- `PORT` - this must be set on each job. Either `mingw`, `msvc` or `cygwin`
-  followed by `32` or `64`.
-- `BOOTSTRAP_FLEXDLL` - must be set on each job. Either `true` or `false`.
-  At present, must be `false` for Cygwin builds. Controls whether flexlink
-  is bootstrapped as part of the test or installed from a binary archive.
-- `FORCE_CYGWIN_UPGRADE`. Default: `0`. Set to `1` to force an upgrade of
-  Cygwin packages as part of the build. Normally a full upgrade is only
-  triggered if the packages installed require it.
-- `BUILD_MODE`. Default: `world.opt`. Either `world.opt`, `steps`, or `C`.
-  Controls whether the build uses the `world.opt` target or the classic
-  `world`, `opt`, `opt.opt` targets. The `C` build is a fast test used to
-  build just enough of the tree to cover the C sources (it's used to test
-  old MSVC compilers).
-- `SDK`. Defaults to Visual Studio 2022. Specifies the exact command to run
-  to set-up the Microsoft build environment.
-- `CYGWIN_DIST`. Default: `64`. Either `64` or `32`, selects 32-bit or 64-bit
-  Cygwin as the build environment.
-
-==== GitHub Actions Continuous Integration (CI)
-
-We use GitHub Actions workflows to test the OCaml compiler and runtime
-in various settings. Some tests are not run by default and are
-triggered by setting a label on the pull request. See below:
-
-- `CI: Full matrix`: expands the test matrix considerably with additional
-  configurations; useful for PRs which affect the "systems" side of the
-  compiler;
-- `CI: Skip testsuite`: turns the tesuite *off* for a PR, which can be useful
-  for PRs which do not affect the compiler _at all_ or while a specific failure
-  is being investigated;
-- `run-crosscompiler-tests`: build various cross-compilers and test them;
-- `run-thread-sanitizer`: build the distribution with the Thread
-  Sanitizer (TSAN), and run the whole testsuite instrumented with TSAN;
-- `run-multicoretests`: run an extensive testsuite covering multicore
-  features.
-
-==== INRIA's Continuous Integration (CI)
-
-INRIA provides a Jenkins continuous integration service that OCaml
-uses, see link:https://ci.inria.fr/ocaml/[]. It provides a wider
-architecture support (MSVC and MinGW, a zsystems s390x machine, and
-various MacOS versions) than the Travis/AppVeyor testing on GitHub,
-but only runs on commits to the trunk or release branches, not on every
-PR.
-
-You do not need to be an INRIA employee to open an account on this
-jenkins service; anyone can create an account there to access build
-logs and manually restart builds. If you
-would like to do this but have trouble doing it, please email
-ocaml-ci-admin@inria.fr.
-
-To be notified by email of build failures, you can subscribe to the
-ocaml-ci-notifications@inria.fr mailing list by visiting
-https://sympa.inria.fr/sympa/info/ocaml-ci-notifications[its web page.]
-
-==== Running INRIA's CI on a publicly available git branch
-
-If you have suspicions that your changes may fail on exotic architectures
-(they touch the build system or the backend code generator,
-for example) and would like to get wider testing than GitHub's CI
-provides, it is possible to manually start INRIA's CI on arbitrary git
-branches even before opening a pull request as follows:
-
-1. Make sure you have an account on Inria's CI as described before.
-
-2. Make sure you have been added to the ocaml project.
-
-3. Prepare a branch with the code you'd like to test, say "mybranch". It
-is probably a good idea to make sure your branch is based on the latest
-trunk.
-
-4. Make your branch publicly available. For instance, you can fork
-OCaml's GitHub repository and then push "mybranch" to your fork.
-
-5. Visit https://ci.inria.fr/ocaml/job/precheck and log in. Click on
-"Build with parameters".
-
-6. Fill in the `REPO_URL` and `BRANCH` fields as appropriate and run the build.
-
-7. You should receive a bunch of e-mails with the build logs for each
-slave and each tested configuration (with and without flambda) attached.
-
-==== Changing what the CI does
-
-INRIA's CI "main" and "precheck" jobs run the script
-tools/ci-build. In particular, when running the CI on a publicly
-available branch via the "precheck" job as explained in the previous
-section, you can edit this script to change what the CI will test.
-
-For instance, parallel builds are only tested for the "trunk"
-branch. In order to use "precheck" to test parallel build on a custom
-branch, add this at the beginning of tools/ci-build:
-
-[source,sh]
-----
-OCAML_JOBS=10
-----
-
-=== The `caml-commits` mailing list
-
-If you would like to receive email notifications of all commits made to the main
-git repository, you can subscribe to the caml-commits@inria.fr mailing list by
-visiting https://sympa.inria.fr/sympa/info/caml-commits[its web page.]
-
-Happy Hacking!
-
-```
-
-### `log://turn_7/env/find_/_-type_f_%5C(_-name_%22minor_gc*%22_-o_-name_%22major_gc*%22_-o_-name_%22sweep*.ml%22_-o`
-scheme=log action=env attrs={"command":"find / -type f \\( -name \"minor_gc*\" -o -name \"major_gc*\" -o -name \"sweep*.ml\" -o -name \"HACKING.adoc\" \\) 2>/dev/null || echo \"no gc files found\"","summary":"find / -type f \\( -name \"minor_gc*\" -o -name \"major_gc*\" -o -name \"sweep*.ml\" -o -name \"HACKING.adoc\" \\) 2>/dev/null || echo \"no gc files found\"","action":"env"}
-
-```
-ran 'find / -type f \( -name "minor_gc*" -o -name "major_gc*" -o -name "sweep*.ml" -o -name "HACKING.adoc" \) 2>/dev/null || echo "no gc files found"', exit=0 (1s). Output: env://turn_7/find_/_-type_f_%5C(_-name_%22minor_gc*%22_-o_-name_%22major_gc*%22_-o_-name_%22sweep*.ml%22_-o_1 (236 tokens), env://turn_7/find_/_-type_f_%5C(_-name_%22minor_gc*%22_-o_-name_%22major_gc*%22_-o_-name_%22sweep*.ml%22_-o_2 (0 tokens)
-```
-
-### `log://turn_7/search/OCaml_garbage_collector_sweeping_major_heap_source_files_github`
-scheme=log action=search attrs={"query":"OCaml garbage collector sweeping major heap source files github","action":"search"}
-
-```
-5 of 12 results for "OCaml garbage collector sweeping major heap source files github" (7 unreachable)
-* https://sanette.github.io/ocaml2.org/learn/tutorials/garbage_collection.html — Garbage Collection – OCaml (7529 tokens)
-  <strong>Calls to read_file open the file but don&#x27;t close it</strong>. Because OCaml uses a full garbage collector chan isn&#x27;t collected until some time later when the minor heap becomes full. In addition, OCaml will not close the channel when it collects the handle&#x27;s memory.
-* https://dev.realworldocaml.org/garbage-collector.html — Understanding the Garbage Collector - Real World OCaml (515 tokens)
-  OCaml’s automatic memory management guarantees that a value will eventually be freed when it’s no longer in use, either via the GC sweeping it or the program terminating. It’s sometimes useful to run extra code just before a value is freed by the GC, for example, to check that a file descriptor has been closed, or that a log message is recorded. Various values cannot have finalizers attached since they aren’t heap-allocated.
-* https://ocamlpro.com/blog/2020_03_23_in_depth_look_at_best_fit_gc — An in-depth Look at OCaml’s new “Best-fit” Garbage Collector Strategy (7147 tokens)
-  The major heap <strong>uses the Mark-and-sweep principle</strong>.
-* https://github.com/realworldocaml/book/blob/master/book/garbage-collector/README.md — README.md (15507 tokens)
-  <strong>When there isn&#x27;t enough memory available to satisfy an allocation request from the pool of allocated heap blocks, the runtime system invokes the garbage collector (GC).</strong> An OCaml program can&#x27;t explicitly free a value when it is done with it.
-* https://www.reddit.com/r/ProgrammingLanguages/comments/1iz8pi8/a_mechanically_verified_garbage_collector_for — A Mechanically Verified Garbage Collector for OCaml : r/ProgrammingLanguages (1342 tokens)
-  <strong>The OCaml GC does force a stop-the-world synchronization at the end of each major GC cycle</strong> -- when the GC is done marking and sweeping the full heap. This is fine, given that major GC cycles are few and far between, so the synchronization costs ...
-```
-
-### `log://turn_7/get/https%3A/github.com/ocaml/ocaml/tree/trunk`
-scheme=log action=get attrs={"path":"https://github.com/ocaml/ocaml/tree/trunk","action":"get"}
-
-```
-https://github.com/ocaml/ocaml/tree/trunk not found
-```
-
-### `log://turn_7/update/getting_HACKING.adoc_%2B_GC_sweeping_files`
-scheme=log action=update attrs={"status":155,"action":"update"}
-
-```
-getting HACKING.adoc + GC sweeping files
-```
-