+68 -32

BOOTSTRAP.adoc

reviewed

··· 17 17 `git status`) 18 18 19 19 2. Configure your source tree by running: 20 20 - 21 21 - ./configure 20 20 + + 21 21 + [source,sh] 22 22 + ---- 23 23 + ./configure 24 24 + ---- 22 25 23 26 3. Bring your system to a stable state. Concretely, this means that the 24 27 boot/ directory should contain a version of ocamlrun and all the 25 28 \*.cm* files of the standard library. This stable state can be reached 26 29 by running 27 27 - 28 28 - make world 30 30 + + 31 31 + [source,sh] 32 32 + ---- 33 33 + make world 34 34 + ---- 29 35 + 30 36 (Actually, running `make coldstart` should be enough but `make world` is 31 37 safer. Similarly, `make world.opt` will also bring you to such a stable ··· 37 43 represented or anything else in the format of .cmi files, etc. 38 44 39 45 5. Run: 40 40 - 41 41 - make coreall 46 46 + + 47 47 + [source,sh] 48 48 + ---- 49 49 + make coreall 50 50 + ---- 42 51 + 43 52 This will rebuild runtime/ocamlrun, ocamlc, etc. 44 53 45 54 6. (optional) The new system can now be tested: 46 46 - 47 47 - echo 'let _ = print_string "Hello world!\n"' > foo.ml 48 48 - ./boot/ocamlrun ./ocamlc -I ./stdlib foo.ml 49 49 - ./runtime/ocamlrun a.out 55 55 + + 56 56 + [source,sh] 57 57 + ---- 58 58 + echo 'let _ = print_string "Hello world!\n"' > foo.ml 59 59 + ./boot/ocamlrun ./ocamlc -I ./stdlib foo.ml 60 60 + ./runtime/ocamlrun a.out 61 61 + ---- 50 62 51 63 7. We now know the system works and can thus build the new boot/ 52 64 binaries: 65 65 + + 66 66 + [source,sh] 67 67 + ---- 68 68 + make bootstrap 69 69 + ---- 53 70 54 54 - make bootstrap 55 55 - 56 56 - = Problems 71 71 + == Problems 57 72 58 73 If you notice that this procedure fails for a given change you are 59 74 trying to implement, please report it so that the procedure can be 60 75 updated to also cope with your change. 61 76 62 62 - = Upstreaming 77 77 + == Upstreaming 63 78 64 79 If you want to upstream your changes, indicate in the message of the 65 80 commit that the changes need a bootstrap. Perform the bootstrap and 66 81 commit the result of the bootstrap separately, after that commit. 67 82 68 68 - = Adding, removing and renaming primitives 83 83 + == Adding, removing and renaming primitives 69 84 70 85 Primitives can be added without having to bootstrap, however it is necessary 71 86 to repeat `make coldstart` in order to use your new primitive in the standard ··· 77 92 78 93 2. Create a temporary stub with the old primitive's name. This stub simply 79 94 passes its arguments on to the new primitive: 80 80 - 81 81 - CAMLprim value caml_old_primitive(value a1, value a2) { 82 82 - return caml_new_primitive(a1, a2); 83 83 - } 95 95 + + 96 96 + [source,c] 97 97 + ---- 98 98 + CAMLprim value caml_old_primitive(value a1, value a2) { 99 99 + return caml_new_primitive(a1, a2); 100 100 + } 101 101 + ---- 84 102 85 103 3. Deal with the addition of the new primitive: 86 86 - 87 87 - make coldstart 104 104 + + 105 105 + [source,sh] 106 106 + ---- 107 107 + make coldstart 108 108 + ---- 88 109 89 110 4. Ensure the system still works: 90 90 - 91 91 - make coreall 111 111 + + 112 112 + [source,sh] 113 113 + ---- 114 114 + make coreall 115 115 + ---- 92 116 93 117 5. Now remove the old primitive stub and issue: 94 94 - 95 95 - make bootstrap 118 118 + + 119 119 + [source,sh] 120 120 + ---- 121 121 + make bootstrap 122 122 + ---- 96 123 97 124 It is desirable for bootstraps to be easily repeatable, so you should commit 98 125 changes after step 4. ··· 102 129 1. Start with a working build of the compiler eg `./configure && make world` 103 130 104 131 2. Remove uses of the primitive, but not the primitive itself. Then ensure the system still works: 105 105 - 106 106 - make coreall 132 132 + + 133 133 + [source,sh] 134 134 + ---- 135 135 + make coreall 136 136 + ---- 107 137 108 138 3. Then, and only then, remove the primitive, and run: 139 139 + + 140 140 + [source,sh] 141 141 + ---- 142 142 + make coreall 143 143 + make bootstrap 144 144 + ---- 109 145 110 110 - make coreall 111 111 - make bootstrap 112 112 - 113 113 - = Bootstrap test script 146 146 + == Bootstrap test script 114 147 115 148 A script is provided (and used on Inria's continuous 116 149 integration infrastructure) to make sure the bootstrap works. This ··· 119 152 a primitive from the runtime. It then makes sure the bootstrap still 120 153 works after these changes. This script can be run locally as follows: 121 154 122 122 - OCAML_ARCH=linux ./tools/ci/inria/bootstrap 155 155 + [source,sh] 156 156 + ---- 157 157 + OCAML_ARCH=linux ./tools/ci/inria/bootstrap 158 158 + ----

+1 -1

CONTRIBUTING.md

reviewed

··· 1 1 # How to contribute changes 2 2 3 3 - :+1::tada: First off, thank you for taking time to contribute! :tada::+1: 3 3 + 👍🎉 First off, thank you for taking time to contribute! 👍🎉 4 4 5 5 The following is a set of guidelines for proposing changes to the 6 6 OCaml distribution. These are just guidelines, not rules, use your

+3

Changes

reviewed

··· 304 304 `Thread.join` on the domain's systhreads. 305 305 (Raphaël Proust, review by Gabriel Scherer) 306 306 307 307 + - #14392: Fix AsciiDoc files, add more markup, xrefs, documentation. 308 308 + (Antonin Décimo, review by Gabriel Scherer and David Allsopp) 309 309 + 307 310 ### Compiler user-interface and warnings: 308 311 309 312 - #12628: Improved error message for unsafe values: print out the full path for

+97 -79

HACKING.adoc

reviewed

··· 1 1 - = Hacking the compiler :camel: 1 1 + = Hacking the compiler 🐫 2 2 3 3 This document is a work-in-progress attempt to provide useful 4 4 information for people willing to inspect or modify the compiler ··· 8 8 If you already have a patch that you would like to contribute to the 9 9 official distribution, please see link:CONTRIBUTING.md[]. 10 10 11 11 - === Your first compiler modification 11 11 + == Your first compiler modification 12 12 13 13 1. Create a new git branch to store your changes. 14 14 + 15 15 + [source,sh] 15 16 ---- 16 17 git checkout -b my-modification 17 18 ---- ··· 23 24 not have this which causes some important development things to be disabled 24 25 (ocamltest and converting C compiler warnings to errors). 25 26 26 26 - 2. Consult link:INSTALL.adoc[] for build instructions. Here is the gist of it: 27 27 + 2. Consult xref:INSTALL.adoc[] for build instructions. Here is the gist of it: 27 28 + 29 29 + [source,sh] 28 30 ---- 29 31 ./configure 30 32 make -j 4 ··· 36 38 3. Try the newly built compiler binaries `ocamlc`, `ocamlopt` or their 37 39 `.opt` version. To try the toplevel, use: 38 40 + 41 41 + [source,sh] 39 42 ---- 40 43 make runtop 41 44 ---- ··· 44 47 45 48 5. Run the testsuite from time to time. 46 49 + 50 50 + [source,sh] 47 51 ---- 48 52 make tests 49 53 ---- ··· 53 57 See also our <<tips,development tips and tricks>>, for example on how to 54 58 <<opam-switch,create an opam switch>> to test your modified compiler. 55 59 56 56 - === What to do 60 60 + == What to do 57 61 58 62 There is always a lot of potential tasks, both for old and 59 63 newcomers. Here are various potential projects: ··· 76 80 clarifying comments can be an excellent contribution to help you, 77 81 next time, and other code readers. 78 82 79 79 - * The https://github.com/ocaml/ocaml[github project] contains a lot of 83 83 + * The https://github.com/ocaml/ocaml[GitHub project] contains a lot of 80 84 pull requests, many of them being in dire need of a review -- we 81 85 have more people willing to contribute changes than to review 82 86 someone else's change. Picking one of them, trying to understand the ··· 109 113 110 114 Parses source files and produces an Abstract Syntax Tree (AST) 111 115 (link:parsing/parsetree.mli[] has lot of helpful comments). See 112 112 - link:parsing/HACKING.adoc[]. 116 116 + xref:parsing/HACKING.adoc[]. 113 117 114 118 The logic for Camlp4 and Ppx preprocessing is not in link:parsing/[], 115 119 but in link:driver/[], see link:driver/pparse.mli[] and ··· 119 123 120 124 Type-checks the AST and produces a typed representation of the program 121 125 (link:typing/typedtree.mli[] has some helpful comments). See 122 122 - link:typing/HACKING.adoc[]. 126 126 + xref:typing/HACKING.adoc[]. 123 127 124 128 ==== The bytecode compiler -- link:bytecomp/[] 125 129 ··· 141 145 and `runtime_NATIVE_ONLY_C_SOURCES` in link:Makefile[] for the list of common, 142 146 bytecode-only, and native-only source files.) 143 147 144 144 - See link:runtime/HACKING.adoc[]. 148 148 + See xref:runtime/HACKING.adoc[]. 145 149 146 150 === Libraries 147 151 ··· 156 160 comments in `.mli` files in the compiler codebase, you can observe the 157 161 result by running 158 162 163 163 + [source,sh] 159 164 ---- 160 165 make html_doc 161 166 ---- ··· 172 177 link:yacc/[]:: The `ocamlyacc` parser generator. We do not recommend 173 178 using it for user projects in need of a parser generator. Please 174 179 consider using and contributing to 175 175 - link:http://gallium.inria.fr/~fpottier/menhir/[menhir] instead, which 180 180 + link:https://gallium.inria.fr/~fpottier/menhir/[menhir] instead, which 176 181 has tons of extra features, lets you write more readable grammars, and 177 182 has excellent documentation. 178 183 179 184 === Complete file listing 180 185 181 181 - BOOTSTRAP.adoc:: instructions for bootstrapping 182 182 - Changes:: what's new with each release 183 183 - CONTRIBUTING.md:: how to contribute to OCaml 184 184 - HACKING.adoc:: this file 185 185 - INSTALL.adoc:: instructions for installation 186 186 - LICENSE:: license and copyright notice 187 187 - Makefile:: main Makefile 188 188 - Makefile.common:: common Makefile definitions 189 189 - README.adoc:: general information on the compiler distribution 190 190 - README.win32.adoc:: general information on the Windows ports of OCaml 191 191 - VERSION:: version string. Run `tools/autogen` after changing. 192 192 - asmcomp/:: native-code compiler and linker 193 193 - boot/:: bootstrap compiler 194 194 - build-aux/:: autotools support scripts 195 195 - bytecomp/:: bytecode compiler and linker 196 196 - compilerlibs/:: the OCaml compiler as a library 197 197 - configure:: configure script 198 198 - configure.ac:: autoconf input file 199 199 - debugger/:: source-level replay debugger 200 200 - driver/:: driver code for the compilers 201 201 - flexdll/:: git submodule -- see link:README.win32.adoc[] 202 202 - lex/:: lexer generator 203 203 - man/:: man pages 204 204 - manual/:: system to generate the manual 205 205 - middle_end/:: the flambda optimisation phase 206 206 - ocamldoc/:: documentation generator 207 207 - ocamltest/:: test driver 208 208 - otherlibs/:: several additional libraries 209 209 - parsing/:: syntax analysis -- see link:parsing/HACKING.adoc[] 210 210 - release-info/:: documentation and tools to prepare releases 211 211 - runtime/:: bytecode interpreter and runtime systems 212 212 - stdlib/:: standard library 213 213 - testsuite/:: tests -- see link:testsuite/HACKING.adoc[] 214 214 - tools/:: various utilities 215 215 - toplevel/:: interactive system 216 216 - typing/:: typechecking -- see link:typing/HACKING.adoc[] 217 217 - utils/:: utility libraries 218 218 - winpthreads/:: winpthreads submodule -- see <<winpthreads,further>> 219 219 - yacc/:: parser generator 186 186 + xref:BOOTSTRAP.adoc[]:: instructions for bootstrapping 187 187 + link:Changes[]:: what’s new with each release 188 188 + link:CONTRIBUTING.md[]:: how to contribute to OCaml 189 189 + xref:HACKING.adoc[]:: this file 190 190 + xref:INSTALL.adoc[]:: instructions for installation 191 191 + link:LICENSE[]:: license and copyright notice 192 192 + link:Makefile[]:: main Makefile 193 193 + link:Makefile.common[]:: common Makefile definitions 194 194 + xref:README.adoc[]:: general information on the compiler distribution 195 195 + xref:README.win32.adoc[]:: general information on the Windows ports of OCaml 196 196 + link:VERSION[]:: version string. Run `make configure` after changing. 197 197 + link:asmcomp/[]:: native-code compiler and linker 198 198 + link:boot/[]:: bootstrap compiler 199 199 + link:build-aux/[]:: autotools support scripts 200 200 + link:bytecomp/[]:: bytecode compiler and linker 201 201 + link:compilerlibs/[]:: the OCaml compiler as a library 202 202 + link:configure[]:: configure script 203 203 + link:configure.ac[]:: autoconf input file 204 204 + link:debugger/[]:: source-level replay debugger 205 205 + link:driver/[]:: driver code for the compilers 206 206 + link:flexdll/[]:: git submodule -- see xref:README.win32.adoc[] 207 207 + link:lex/[]:: lexer generator 208 208 + link:man/[]:: man pages 209 209 + link:manual/[]:: system to generate the manual 210 210 + link:middle_end/[]:: the flambda optimisation phase 211 211 + link:ocamldoc/[]:: documentation generator 212 212 + link:ocamltest/[]:: test driver 213 213 + link:otherlibs/[]:: several additional libraries 214 214 + link:parsing/[]:: syntax analysis -- see xref:parsing/HACKING.adoc[] 215 215 + link:release-info/[]:: documentation and tools to prepare releases 216 216 + link:runtime/[]:: bytecode interpreter and runtime systems 217 217 + link:stdlib/[]:: standard library 218 218 + link:testsuite/[]:: tests -- see xref:testsuite/HACKING.adoc[] 219 219 + link:tools/[]:: various utilities 220 220 + link:toplevel/[]:: interactive system 221 221 + link:typing/[]:: typechecking -- see xref:typing/HACKING.adoc[] 222 222 + link:utils/[]:: utility libraries 223 223 + link:winpthreads/[]:: winpthreads submodule -- see <<winpthreads,further>> 224 224 + link:yacc/[]:: parser generator 220 225 221 226 [#tips] 222 227 == Development tips and tricks 223 228 224 224 - === Keep merge commits when merging and cherry-picking Github PRs 229 229 + === Keep merge commits when merging and cherry-picking GitHub PRs 225 230 226 226 - Having the Github PR number show up in the git log is very useful for 231 231 + Having the GitHub PR number show up in the git log is very useful for 227 232 later triaging. We recently disabled the "Rebase and merge" button, 228 233 precisely because it does not produce a merge commit. 229 234 ··· 233 238 option.) You should also use the `-x` option to include the hash of 234 239 the original commit in the commit message. 235 240 241 241 + [source,sh] 236 242 ---- 237 243 git cherry-pick -x -m 1 <merge-commit-hash> 238 244 ---- ··· 248 254 https://editorconfig.org/#download[plugins]. 249 255 250 256 [#opam-switch] 251 251 - === Testing with `opam` 257 257 + === Testing with opam 252 258 253 259 If you are working on a development version of the compiler, you can create an 254 260 opam switch from it by running the following from the development repository: 255 261 262 262 + [source,sh] 256 263 ----- 257 264 opam switch create . --empty 258 265 opam install . ··· 262 269 git repository, you can build a switch directly (without cloning their 263 270 work locally) by pinning: 264 271 272 272 + [source,sh] 265 273 ---- 266 274 opam switch create my-switch-name --empty 267 267 - opam pin add ocaml-variants git+https://$REPO#branch 275 275 + opam pin add ocaml-variants "git+https://$REPO#branch" 268 276 ---- 269 277 270 270 - ==== Incremental builds with `opam` 278 278 + ==== Incremental builds with opam 271 279 272 280 This section documents some tips to speed up your workflow when you need to 273 281 alternate between testing your branch and patching the compiler. ··· 276 284 ===== Initial setup 277 285 278 286 For the rest of the section to work, you'll need your compiler to be 279 279 - configured in the same way as `opam` would have configured it. The simplest 287 287 + configured in the same way as opam would have configured it. The simplest 280 288 way is to run the normal commands for the switch initialization, with the extra 281 289 `--inplace-build` flag: 282 290 291 291 + [source,sh] 283 292 ----- 284 293 opam switch create . --empty 285 294 opam install . --inplace-build ··· 287 296 288 297 However, if you need specific configuration options, you can also configure it 289 298 manually, as long as you make sure that the configuration prefix is the one 290 290 - where `opam` would install the compiler. 299 299 + where opam would install the compiler. 291 300 You will then need to install the compiler, either from the working directory 292 301 (that you must build yourself) or using the regular sandboxed builds. 293 302 303 303 + [source,sh] 294 304 ----- 295 305 # Example with regular opam build 296 306 opam switch create . --empty ··· 298 308 ./configure --prefix=$(opam var prefix) # put extra configuration args here 299 309 ----- 300 310 311 311 + [source,sh] 301 312 ----- 302 313 # Example with installation from the current directory 303 314 opam switch create . --empty ··· 309 320 ===== Basic workflow 310 321 311 322 We will assume that the workflow alternates between work on the compiler and 312 312 - external (`opam`-related) commands. 323 323 + external (opam-related) commands. 313 324 As an example, debugging an issue in the compiler can be done by a first step 314 314 - that triggers the issue (by installing a given `opam` package), then adding 325 325 + that triggers the issue (by installing a given opam package), then adding 315 326 some logging to the compiler, re-trigger the issue, and based on the logs either 316 327 add more logging, or try a patch, and so on. 317 328 ··· 328 339 329 340 In our case, we need to build the compiler, and when we've built everything 330 341 that we need then we run `opam custom-install ocaml-variants -- make install`. 331 331 - This will make `opam` remove the previously installed version of the compiler 342 342 + This will make opam remove the previously installed version of the compiler 332 343 (if any), then install the new one in its stead. 333 344 345 345 + [source,sh] 334 346 ----- 335 347 # reinstall the compiler, and rebuild all opam packages 336 348 opam custom-install ocaml-variants -- make install 337 349 ----- 338 350 339 339 - Since most `opam` packages depend on the compiler, this will trigger a 351 351 + Since most opam packages depend on the compiler, this will trigger a 340 352 reinstallation of all the packages in the switch. 341 353 If you want to avoid that (for instance, your patch only adds some logging 342 354 so you expect the core libraries and all the already compiled packages to be ··· 345 357 changing even slightly one of the core libraries' files, you will likely 346 358 get inconsistent assumptions errors later. 347 359 360 360 + [source,sh] 348 361 ----- 349 362 # reinstall the compiler, leaving the opam packages untouched -- unsafe! 350 363 opam custom-install --no-recompilations ocaml-variants -- make install ··· 352 365 353 366 Note about the first installation: 354 367 When you start from an empty switch, and install a compiler (in our case, 355 355 - the `ocaml-variants` package provided by the compiler's `opam` file), then 368 368 + the `ocaml-variants` package provided by the compiler's opam file), then 356 369 a number of additional packages are installed to ensure that the switch 357 370 will work correctly. Mainly, the `ocaml` package needs to be installed, 358 358 - and while it's done automatically when using regular `opam` commands, the 371 371 + and while it's done automatically when using regular opam commands, the 359 372 `custom-install` plugin will not force installation of dependencies. 360 373 Moreover, if you try to fix the problem by manually installing the `ocaml` 361 361 - package, `opam` will try to recompile `ocaml-variants`, using the default 374 374 + package, opam will try to recompile `ocaml-variants`, using the default 362 375 instructions. You can get around this by running 363 376 `opam reinstall --forget-pending` just after the `opam custom-install` command 364 377 and just before the `opam install ocaml command`. 365 378 Full example: 366 379 380 380 + [source,sh] 367 381 ----- 368 382 opam switch create . --empty 369 383 ./configure --prefix=$(opam var prefix) --disable-ocamldoc --disable-ocamltest ··· 381 395 bytecode tools are installed, whereas with a raw `make install` you will have 382 396 stale native binaries remaining in your switch. 383 397 Since it's significantly faster to build the bytecode version of the tools, 384 384 - and many `opam` packages will pick the native version of the compilers if 398 398 + and many opam packages will pick the native version of the compilers if 385 399 present and the bytecode version otherwise, you can build your initial switch 386 400 with the native versions (to get quickly to a state where a bug appears), 387 401 then clean your working directory and start building bytecode tools only ··· 389 403 390 404 ===== Without `opam-custom-install` 391 405 392 392 - You can achieve some improvements using built-in `opam` commands. 406 406 + You can achieve some improvements using built-in opam commands. 393 407 394 408 Using `opam install . --assume-built` will simply remove the 395 409 package for the compiler, then run the installation instructions ··· 400 414 401 415 You can also run `make install` manually, which will not trigger a 402 416 recompilation, but will not remove the previous version either and can 403 403 - mess with `opam`'s tracking of installed files. 417 417 + mess with opam's tracking of installed files. 404 418 405 419 === Useful Makefile targets and options 406 420 407 407 - Besides the targets listed in link:INSTALL.adoc[] for build and 421 421 + Besides the targets listed in xref:INSTALL.adoc[] for build and 408 422 installation, the following targets may be of use: 409 423 410 424 `make runtop` :: builds and runs the ocaml toplevel of the distribution ··· 417 431 418 432 `make depend`:: Regenerate the `.depend` file. Should be used each time new dependencies are added between files. 419 433 420 420 - `make -C testsuite parallel`:: see link:testsuite/HACKING.adoc[] 434 434 + `make -C testsuite parallel`:: see xref:testsuite/HACKING.adoc[] 421 435 422 436 You can use `make foo V=1` to build the target foo and show full 423 423 - commands instead of abbreviated names like OCAMLC, etc. This can be 437 437 + commands instead of abbreviated names like `OCAMLC`, etc. This can be 424 438 useful to know the flags to use to manually rebuild a file. 425 439 426 440 Additionally, there are some developer specific targets in link:Makefile.dev[]. ··· 468 482 link:boot/[] directory. These bytecode images are used once the 469 483 bytecode runtime (which is written in C) has been built to compile the 470 484 standard library and then to build a fresh compiler. Details can be 471 471 - found in link:BOOTSTRAP.adoc[]. 485 485 + found in xref:BOOTSTRAP.adoc[]. 472 486 473 487 === Speeding up builds 474 488 475 489 Once you've built a natively-compiled `ocamlc.opt`, you can use it to 476 490 speed up future builds by copying it to `boot`: 477 491 492 492 + [source,sh] 478 493 ---- 479 494 cp ocamlc.opt boot/ 480 495 ---- ··· 498 513 version installed with merlin and dune, you can just run the following from the 499 514 compiler sources: 500 515 516 516 + [source,sh] 501 517 ---- 502 518 ./configure # if not already done 503 519 make clean-for-dune && dune build @libs ··· 604 620 If you're using a version of GNU Autoconf that differs from our CI, 605 621 then the generated `configure` script might differ too. The latest 606 622 Ubuntu LTS packages may be used as a reasonable base to generate this 607 607 - file. Using a Docker image with GNU Autoconf installed, and `git 608 608 - rebase --exec`, one can properly regenerate the `configure` script for 609 609 - each commit in a branch. 623 623 + file. Using a Docker image with GNU Autoconf installed, and 624 624 + `git rebase --exec`, one can properly regenerate the `configure` 625 625 + script for each commit in a branch. 610 626 611 627 [source,sh] 612 628 ---- ··· 632 648 machine, you can use the configuration values and run command taken from 633 649 link:tools/ci/actions/runner.sh[]: 634 650 651 651 + [source,sh] 635 652 ---- 636 653 bash -ex tools/ci/actions/runner.sh configure 637 654 ---- ··· 642 659 set explicitly to reproduce them locally. 643 660 644 661 `Changes updated` checks that the link:Changes[] file has been modified 645 645 - (hopefully to add a new entry). It can be disabled by including "_(no change 646 646 - entry needed)_" in one of your commit messages -- but in general all patches 647 647 - submitted should come with a Changes entry; see the guidelines in 648 648 - link:CONTRIBUTING.md[]. 662 662 + (hopefully to add a new entry). In general all patches submitted should come 663 663 + with a Changes entry; see the guidelines in link:CONTRIBUTING.md[]. 649 664 650 665 The Windows ports take a long time to test - INRIA's precheck service is the 651 666 best to use when all 6 Windows ports need testing for a branch, but the ··· 693 708 INRIA provides a Jenkins continuous integration service that OCaml 694 709 uses, see link:https://ci.inria.fr/ocaml/[]. It provides a wider 695 710 architecture support (MSVC and MinGW, a zsystems s390x machine, and 696 696 - various MacOS versions) than the Travis/AppVeyor testing on github, 711 711 + various MacOS versions) than the Travis/AppVeyor testing on GitHub, 697 712 but only runs on commits to the trunk or release branches, not on every 698 713 PR. 699 714 ··· 711 726 712 727 If you have suspicions that your changes may fail on exotic architectures 713 728 (they touch the build system or the backend code generator, 714 714 - for example) and would like to get wider testing than github's CI 729 729 + for example) and would like to get wider testing than GitHub's CI 715 730 provides, it is possible to manually start INRIA's CI on arbitrary git 716 731 branches even before opening a pull request as follows: 717 732 ··· 729 744 5. Visit https://ci.inria.fr/ocaml/job/precheck and log in. Click on 730 745 "Build with parameters". 731 746 732 732 - 6. Fill in the REPO_URL and BRANCH fields as appropriate and run the build. 747 747 + 6. Fill in the `REPO_URL` and `BRANCH` fields as appropriate and run the build. 733 748 734 749 7. You should receive a bunch of e-mails with the build logs for each 735 750 slave and each tested configuration (with and without flambda) attached. ··· 745 760 branch. In order to use "precheck" to test parallel build on a custom 746 761 branch, add this at the beginning of tools/ci-build: 747 762 763 763 + [source,sh] 748 764 ---- 749 765 OCAML_JOBS=10 750 766 ---- ··· 765 781 766 782 To recreate the `winpthreads` repository from upstream, you can do: 767 783 784 784 + [source,sh] 768 785 ---- 769 786 git clone -o upstream https://git.code.sf.net/p/mingw-w64/mingw-w64 winpthreads 770 787 cd winpthreads ··· 776 793 As subtree splitting is deterministic, repeating these operations later will 777 794 allow to update `master`, for instance by: 778 795 796 796 + [source,sh] 779 797 ---- 780 798 git fetch upstream 781 799 git checkout upstream/master

+83 -44

INSTALL.adoc

reviewed

··· 7 7 ** For GNU/Linux + 8 8 The GNU C Compiler (`gcc`) is recommended as the bytecode interpreter takes 9 9 advantage of GCC-specific features to enhance performance. GCC is the standard 10 10 - compiler under Linux and many other systems. 10 10 + compiler under Linux and many other systems. Clang (`clang`) should also be a 11 11 + safe choice. 11 12 12 13 ** For BSDs + 13 13 - `clang` is the default C compiler on BSDs - also works fine. 14 14 + Clang (`clang`) is the default C compiler on BSDs - also works fine. 14 15 15 16 ** For macOS + 16 16 - `clang` is the default C compiler under macOS. If macOS complains 17 17 - no C compiler was installed while OCaml is building, please run 18 18 - command `xcode-select --install` to install command-line tools and 19 19 - required libraries and header files. 17 17 + Apple Clang (`clang`) is the default C compiler under macOS. If macOS 18 18 + complains that no C compiler is installed while OCaml is building, run 19 19 + command `xcode-select --install` to install command-line tools, required 20 20 + libraries, and header files. 20 21 21 22 ** For other Unix-like systems + 22 23 It is recommended to use `gcc` or `clang` instead of the C compiler ··· 25 26 ** For Windows + 26 27 To produce native Windows executables from OCaml sources, you need to use 27 28 the MSVC or MinGW-w64 ports of OCaml, described in file 28 28 - https://github.com/ocaml/ocaml/blob/trunk/README.win32.adoc[README.win32.adoc]. + 29 29 - For a more Unix-like experience, you can use WSL, the 30 30 - https://aka.ms/wsl[Windows Subsystem for Linux], or the 31 31 - https://www.cygwin.com/[Cygwin environment]. You will need the 29 29 + xref:README.win32.adoc[]. + 30 30 + For a more Unix-like experience, you can use the 31 31 + https://aka.ms/wsl[Windows Subsystem for Linux] (WSL), or the 32 32 + https://www.cygwin.com/[Cygwin environment]. With Cygwin, you will need the 32 33 GCC compiler (package `gcc-core` or `gcc`). 33 34 34 34 - * GNU `make`, as well as POSIX-compatible `awk` and `sed` are required. 35 35 + * GNU Make (`make` or `gmake`), as well as POSIX-compatible `awk` and `sed` are 36 36 + required. 35 37 36 38 * A POSIX-compatible `diff` is necessary to run the test suite. 37 39 ··· 53 55 54 56 From the top directory, do: 55 57 56 56 - ./configure 58 58 + [source,sh] 59 59 + ---- 60 60 + ./configure 61 61 + ---- 57 62 58 63 This generates the three configuration files `Makefile.config`, 59 64 `runtime/caml/m.h` and `runtime/caml/s.h`. 60 65 61 66 The `configure` script accepts options that can be discovered by running: 62 67 63 63 - ./configure --help 68 68 + [source,sh] 69 69 + ---- 70 70 + ./configure --help 71 71 + ---- 64 72 65 65 - Some options or variables like LDLIBS may not be taken into account 73 73 + Some options or variables like `LDLIBS` may not be taken into account 66 74 by the OCaml build system at the moment. Please report an issue if you 67 75 discover such a variable or option and this causes troubles to you. 68 76 69 77 Examples: 70 78 71 79 * Standard installation in `/usr/{bin,lib,man}` instead of `/usr/local`: 72 72 - ./configure --prefix=/usr 73 73 - 80 80 + + 81 81 + [source,sh] 82 82 + ---- 83 83 + ./configure --prefix=/usr 84 84 + ---- 74 85 75 86 * On a Linux x86-64 host, to build a 32-bit version of OCaml: 76 76 - 77 77 - ./configure --build=x86_64-pc-linux-gnu --host=i686-linux-gnu 87 87 + + 88 88 + [source,sh] 89 89 + ---- 90 90 + ./configure --build=x86_64-pc-linux-gnu --host=i686-linux-gnu 91 91 + ---- 78 92 79 93 * For AIX 7.x with the IBM compiler `xlc`: 80 80 - 81 81 - ./configure CC=xlc 82 94 + 83 83 - By default, build is 32-bit. For 64-bit build, please set environment variable `OBJECT_MODE=64` 95 95 + [source,sh] 96 96 + ---- 97 97 + ./configure CC=xlc 98 98 + ---- 99 99 + + 100 100 + By default, the build is 32-bit. For the 64-bit build, set the environment variable `OBJECT_MODE=64` 84 101 for _both_ `configure` and `make world` phases. Note, if this variable is set for only one phase, 85 102 your build will break (`ocamlrun` segfaults). 86 86 - + 103 103 + 87 104 * For Solaris/Illumos on SPARC machines with Sun PRO compiler only 64-bit 88 105 bytecode target is supported (32-bit fails due to alignment issues; the optimization 89 106 is preset to `-O4` for inlining): 107 107 + + 108 108 + [source,sh] 109 109 + ---- 110 110 + ./configure CC="cc -m64" 111 111 + ---- 90 112 91 91 - ./configure CC="cc -m64" 92 92 - + 93 113 If something goes wrong during the automatic configuration, or if the generated 94 114 files cause errors later on, then look at the template files: 95 115 96 96 - Makefile.config.in 97 97 - Makefile.build_config.in 98 98 - runtime/caml/m.h.in 99 99 - runtime/caml/s.h.in 100 100 - + 116 116 + ---- 117 117 + Makefile.config.in 118 118 + Makefile.build_config.in 119 119 + runtime/caml/m.h.in 120 120 + runtime/caml/s.h.in 121 121 + ---- 122 122 + 101 123 for guidance on how to edit the generated files by hand. 102 124 103 125 == Building the compiler 104 126 105 127 From the top directory, do: 106 106 - 107 107 - make 128 128 + [source,sh] 129 129 + ---- 130 130 + make 131 131 + ---- 108 132 109 133 This builds the OCaml compiler for the first time. This phase is 110 134 fairly verbose; consider redirecting the output to a file: 111 135 112 112 - make > make.log 2>&1 # in sh 113 113 - make >& make.log # in csh 136 136 + [source,sh] 137 137 + ---- 138 138 + make > make.log 2>&1 # in sh 139 139 + make >& make.log # in csh 140 140 + ---- 114 141 115 142 == (Optional) Running the testsuite 116 143 117 144 To be sure everything works well, you can run the test suite 118 145 that comes with the compiler. To do so, do: 119 146 120 120 - make tests 147 147 + [source,sh] 148 148 + ---- 149 149 + make tests 150 150 + ---- 121 151 122 152 == Installing the compiler 123 153 ··· 143 173 144 174 From the top directory, become superuser and do: 145 175 146 146 - make install 176 176 + [source,sh] 177 177 + ---- 178 178 + make install 179 179 + ---- 147 180 148 181 Installation is complete. Time to clean up. From the toplevel directory, 149 182 do: 150 183 151 151 - make clean 184 184 + [source,sh] 185 185 + ---- 186 186 + make clean 187 187 + ---- 152 188 153 189 After installation, do *not* strip the `ocamldebug` executables. 154 190 This is a mixed-mode executable (containing both compiled C ··· 161 197 this file. 162 198 163 199 Check the files `m.h` and `s.h` in `runtime/caml/`. 164 164 - Wrong endianness or alignment constraints in `machine.h` will 200 200 + Wrong endianness or alignment constraints in `m.h` will 165 201 immediately crash the bytecode interpreter. 166 202 167 203 If you get a "segmentation violation" signal, check the limits on the stack size ··· 205 241 generates code for a different machine, named the _target_. To build a cross 206 242 compiler you first need to have a non-cross compiler of the same version 207 243 installed in your `$PATH`. You can install that standard non-cross compiler by 208 208 - any means, for instance using `opam` or compiling it manually from source. Note 244 244 + any means, for instance using opam or compiling it manually from source. Note 209 245 though that the version of the non-cross compiler must match the version of the 210 246 cross compiler since the cross compiler will be compiled by the non-cross 211 247 compiler: the cross compiler will combine code compiled from source with the ··· 217 253 setting the `TARGET_LIBDIR` variable. For instance, with the GCC MinGW cross 218 254 compiler installed, one may use: 219 255 220 220 - .... 256 256 + [source,sh] 257 257 + ---- 221 258 ./configure --prefix=$PWD/cross --target=x86_64-w64-mingw32 TARGET_LIBDIR='C:\somedir' ... 222 259 make crossopt -j 223 260 make installcross 224 224 - .... 261 261 + ---- 225 262 226 263 Notes: 227 264 ··· 239 276 If you have built a cross compiler to a Unix target, you can simply run as 240 277 usual: 241 278 242 242 - .... 279 279 + [source,sh] 280 280 + ---- 243 281 cross/bin/ocamlopt.opt -o test test.ml 244 244 - .... 282 282 + ---- 245 283 246 284 If you have built a Unix-to-Windows cross compiler, you must first make sure 247 285 that `ocamlopt` can find the `flexlink` executable in `$PATH` when it needs to 248 286 link. Bootstrapping `flexdll` builds a `flexlink.exe` (note the `.exe`!), so you 249 287 can: 250 288 251 251 - .... 289 289 + [source,sh] 290 290 + ---- 252 291 ln -s flexlink.exe cross/bin/flexlink 253 292 (export PATH="$PWD/cross/bin:$PATH"; ocamlopt.opt.exe -o test.exe test.ml) 254 254 - .... 293 293 + ---- 255 294 256 295 or any other possibility to make sure `ocamlopt` can invoke `flexlink`.

+14 -14

README.adoc

reviewed

··· 1 1 + = README 2 2 + 1 3 [CAUTION] 2 4 ==== 3 5 The developer team released OCaml 5.0.0 in December 2022. OCaml 5.x features a ··· 14 16 |===== 15 17 | Branch `trunk` | Branch `5.4` | Branch `5.3` | Branch `5.2` | Branch `4.14` 16 18 17 17 - | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=trunk["Github CI Build Status (trunk branch)", 19 19 + | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=trunk["GitHub CI Build Status (trunk branch)", 18 20 link="https://github.com/ocaml/ocaml/actions?query=workflow%3ABuild"] 19 19 - image:https://github.com/ocaml/ocaml/workflows/Hygiene/badge.svg?branch=trunk["Github CI Hygiene Status (trunk branch)", 21 21 + image:https://github.com/ocaml/ocaml/workflows/Hygiene/badge.svg?branch=trunk["GitHub CI Hygiene Status (trunk branch)", 20 22 link="https://github.com/ocaml/ocaml/actions?query=workflow%3AHygiene"] 21 23 image:https://ci.appveyor.com/api/projects/status/github/ocaml/ocaml?branch=trunk&svg=true["AppVeyor Build Status (trunk branch)", 22 24 link="https://ci.appveyor.com/project/avsm/ocaml"] 23 23 - | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=5.4["Github CI Build Status (5.4 branch)", 25 25 + | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=5.4["GitHub CI Build Status (5.4 branch)", 24 26 link="https://github.com/ocaml/ocaml/actions?query=workflow%3ABuild"] 25 27 image:https://ci.appveyor.com/api/projects/status/github/ocaml/ocaml?branch=5.4&svg=true["AppVeyor Build Status (5.4 branch)", 26 28 link="https://ci.appveyor.com/project/avsm/ocaml"] 27 27 - | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=5.3["Github CI Build Status (5.3 branch)", 29 29 + | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=5.3["GitHub CI Build Status (5.3 branch)", 28 30 link="https://github.com/ocaml/ocaml/actions?query=workflow%3ABuild"] 29 31 image:https://ci.appveyor.com/api/projects/status/github/ocaml/ocaml?branch=5.3&svg=true["AppVeyor Build Status (5.3 branch)", 30 32 link="https://ci.appveyor.com/project/avsm/ocaml"] 31 31 - | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=5.2["Github CI Build Status (5.2 branch)", 33 33 + | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=5.2["GitHub CI Build Status (5.2 branch)", 32 34 link="https://github.com/ocaml/ocaml/actions?query=workflow%3ABuild"] 33 35 image:https://ci.appveyor.com/api/projects/status/github/ocaml/ocaml?branch=5.2&svg=true["AppVeyor Build Status (5.2 branch)", 34 36 link="https://ci.appveyor.com/project/avsm/ocaml"] 35 35 - | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=4.14["Github CI Build Status (4.14 branch)", 37 37 + | image:https://github.com/ocaml/ocaml/workflows/Build/badge.svg?branch=4.14["GitHub CI Build Status (4.14 branch)", 36 38 link="https://github.com/ocaml/ocaml/actions?query=workflow%3ABuild"] 37 39 image:https://ci.appveyor.com/api/projects/status/github/ocaml/ocaml?branch=4.14&svg=true["AppVeyor Build Status (4.14 branch)", 38 40 link="https://ci.appveyor.com/project/avsm/ocaml"] 39 41 |===== 40 42 41 41 - = README = 42 42 - 43 43 == Overview 44 44 45 45 OCaml is a functional, statically-typed programming language from the ··· 86 86 87 87 == Installation 88 88 89 89 - See the file link:INSTALL.adoc[] for installation instructions on 89 89 + See the file xref:INSTALL.adoc[] for installation instructions on 90 90 machines running Unix, Linux, macOS, WSL and Cygwin. For native Microsoft 91 91 - Windows, see link:README.win32.adoc[]. 91 91 + Windows, see xref:README.win32.adoc[]. 92 92 93 93 == Documentation 94 94 ··· 146 146 147 147 == Contributing 148 148 149 149 - For information on contributing to OCaml, see link:HACKING.adoc[] and 149 149 + For information on contributing to OCaml, see xref:HACKING.adoc[] and 150 150 link:CONTRIBUTING.md[]. 151 151 152 152 == Separately maintained components 153 153 154 154 Some libraries and tools which used to be part of the OCaml distribution are 155 155 - now maintained separately and distributed as OPAM packages. 155 155 + now maintained separately and distributed as opam packages. 156 156 Please use the issue trackers at their respective new homes: 157 157 158 158 |==== 159 159 - | Library | Removed since | OPAM package 159 159 + | Library | Removed since | opam package 160 160 161 161 | https://github.com/ocaml/camlp-streams/issues[The Stream and Genlex standard library modules] | OCaml 5.0 | `camlp-streams` 162 162 | https://github.com/ocaml/graphics/issues[The Graphics library] | OCaml 4.09 | `graphics` ··· 166 166 | https://github.com/garrigue/labltk/issues[The LablTk library] | OCaml 4.02 | `labltk` 167 167 | https://github.com/ocaml/dbm/issues[The CamlDBM library] | OCaml 4.00 | `dbm` 168 168 | https://github.com/xavierleroy/ocamltopwin/issues[The OCamlWinTop Windows toplevel] | OCaml 4.00 | none 169 169 - |===== 169 169 + |====

+64 -26

README.win32.adoc

reviewed

··· 43 43 44 44 Cygwin aims to provide a Unix-like environment on Windows, and the build 45 45 procedure for it is the same as for other flavours of Unix. See 46 46 - link:INSTALL.adoc[] for full instructions. 46 46 + xref:INSTALL.adoc[] for full instructions. 47 47 48 48 OCaml requires Windows 8 or later and naturally the 64-bit versions need a 49 49 64-bit edition of Windows (note that this is both to run *and* build). ··· 118 118 Once you have started a Command Prompt, you can verify that you have the 119 119 compiler you are expecting simply by running: 120 120 121 121 - cl 122 122 - Microsoft (R) C/C++ Optimizing Compiler Version 19.38.33133 for x64 123 123 - ... 121 121 + [source,console] 122 122 + ---- 123 123 + > cl 124 124 + Microsoft (R) C/C++ Optimizing Compiler Version 19.38.33133 for x64 125 125 + ... 126 126 + ---- 124 127 125 128 You then need to start Cygwin from this Command Prompt. Assuming you have 126 129 installed it to its default location of `C:\cygwin64`, simply run: 127 130 128 128 - C:\cygwin64\bin\mintty - 131 131 + [source,bat] 132 132 + ---- 133 133 + C:\cygwin64\bin\mintty - 134 134 + ---- 129 135 130 136 (note the space and hyphen at the end of the command). 131 137 ··· 139 145 the beginning of `PATH`, before Cygwin's `/usr/bin`. You can automate this from 140 146 the top-level of the OCaml distribution by running: 141 147 142 142 - eval $(tools/msvs-promote-path) 148 148 + [source,sh] 149 149 + ---- 150 150 + eval $(tools/msvs-promote-path) 151 151 + ---- 143 152 144 153 If you forget to do this, `make` will fail relatively 145 154 quickly as it will be unable to link `ocamlrun`. 146 155 147 156 For 64-bit, now run: 148 157 149 149 - ./configure --build=x86_64-pc-cygwin --host=x86_64-pc-windows 158 158 + [source,sh] 159 159 + ---- 160 160 + ./configure --build=x86_64-pc-cygwin --host=x86_64-pc-windows 161 161 + ---- 150 162 151 163 or, for 32-bit: 152 164 153 153 - ./configure --build=x86_64-pc-cygwin --host=i686-pc-windows 165 165 + [source,sh] 166 166 + ---- 167 167 + ./configure --build=x86_64-pc-cygwin --host=i686-pc-windows 168 168 + ---- 154 169 155 170 If you wish to compile with Clang, add `CC=clang-cl`. 156 171 157 172 Finally, use `make` to build the system, e.g. 158 173 159 159 - make 160 160 - make install 174 174 + [source,sh] 175 175 + ---- 176 176 + make 177 177 + make install 178 178 + ---- 161 179 162 180 After installing, it is not necessary to keep the Cygwin installation (although 163 181 you may require it to build additional third party libraries and tools). You ··· 169 187 like to copy the `tools/msvs-promote-path` script and add the `eval` line to 170 188 your `~/.bashrc` file. 171 189 172 172 - * The Microsoft Visual C/C++ compiler does not implement "computed gotos", and 173 173 - therefore generates inefficient code for `runtime/interp.c`. Consequently, 174 174 - the performance of bytecode programs is about 2/3 of that obtained under 175 175 - Unix/GCC, Cygwin or MinGW-w64 on similar hardware. 190 190 + * The Microsoft Visual C/C++ compiler does not implement "computed gotos" (also 191 191 + known as "labels as values"), and therefore generates inefficient code for the 192 192 + bytecode interpreter in `runtime/interp.c`. Consequently, the performance of 193 193 + bytecode programs is about 2/3 of that obtained under Unix/GCC, Cygwin or 194 194 + MinGW-w64 on similar hardware. The clang-cl compiler supports the "computed 195 195 + gotos" extension. 176 196 177 177 - * Libraries available in this port: `dynlink`, `num`, 178 178 - `str`, `threads`, and large parts of `unix`. 197 197 + * Libraries available in this port: `dynlink`, `str`, `threads`, and large parts 198 198 + of `unix`. 179 199 180 200 * The replay debugger is partially supported (no reverse execution). 181 201 ··· 211 231 212 232 For 64-bit, now run: 213 233 214 214 - ./configure --build=x86_64-pc-cygwin --host=x86_64-w64-mingw32 234 234 + [source,sh] 235 235 + ---- 236 236 + ./configure --build=x86_64-pc-cygwin --host=x86_64-w64-mingw32 237 237 + ---- 215 238 216 239 or, for 32-bit: 217 240 218 218 - ./configure --build=x86_64-pc-cygwin --host=i686-w64-mingw32 241 241 + [source,sh] 242 242 + ---- 243 243 + ./configure --build=x86_64-pc-cygwin --host=i686-w64-mingw32 244 244 + ---- 219 245 220 246 Finally, use `make` to build the system, e.g. 221 247 222 222 - make 223 223 - make install 248 248 + [source,sh] 249 249 + ---- 250 250 + make 251 251 + make install 252 252 + ---- 224 253 225 254 After installing, you will need to ensure that `ocamlopt` (or `ocamlc -custom`) 226 255 can access the C compiler. You can do this either by using OCaml from Cygwin's 227 256 bash or by adding Cygwin's bin directory (e.g. `C:\cygwin64\bin`) to your 228 257 `PATH`. 229 258 230 230 - * Libraries available in this port: `dynlink`, `num`, 231 231 - `str`, `threads`, and large parts of `unix`. 259 259 + * Libraries available in this port: `dynlink`, `str`, `threads`, and large parts 260 260 + of `unix`. 232 261 233 262 * The replay debugger is partially supported (no reverse execution). 234 263 ··· 249 278 https://github.com/ocaml/flexdll/releases 250 279 * Cloning the git repository by running: 251 280 + 252 252 - git clone https://github.com/ocaml/flexdll.git 281 281 + [source,sh] 282 282 + ---- 283 283 + git clone https://github.com/ocaml/flexdll.git 284 284 + ---- 253 285 254 286 * If you are compiling from a git clone of the OCaml repository, instead of 255 287 using a sources tarball, you can run: 256 288 + 257 257 - git submodule update --init 289 289 + [source,sh] 290 290 + ---- 291 291 + git submodule update --init 292 292 + ---- 258 293 259 294 OCaml is then compiled normally for the port you require. 260 295 261 261 - make 262 262 - make install 296 296 + [source,sh] 297 297 + ---- 298 298 + make 299 299 + make install 300 300 + ---- 263 301 264 302 * `make install` will install FlexDLL by placing `flexlink.exe` 265 303 (and the default manifest file for the Microsoft port) in `bin/` and the

+5 -3

parsing/HACKING.adoc

reviewed

··· 9 9 10 10 link:parser.mly[parser.mly]:: This file contains the grammar used to 11 11 generated the parser -- using the 12 12 - link:http://gallium.inria.fr/~fpottier/menhir/[menhir] parser 12 12 + link:https://gallium.inria.fr/~fpottier/menhir/[menhir] parser 13 13 generator, which is an external tool that you need to install if you 14 14 wish to modify the parser. 15 15 16 16 - === Working on the parser grammar 16 16 + == Working on the parser grammar 17 17 18 18 To avoid depending on an external tool, the compiler build system does 19 19 not rebuild the parser from the source grammar link:parser.mly[] each ··· 25 25 link:../Makefile.menhir[] for the details of the various 26 26 Menhir-related targets and their use. 27 27 28 28 - ==== Testing the grammar 28 28 + === Testing the grammar 29 29 30 30 The root Makefile contains a `build-all-asts` target that will build, 31 31 for each source `.ml` or `.mli` file in the repository, a `.ml.ast` or ··· 34 34 This rule is rather slow to run, and can safely be run in parallel, so 35 35 we recommend using `-j` (without a number) to maximize parallelism: 36 36 37 37 + [source,sh] 37 38 ---- 38 39 make -j build-all-asts 39 40 ---- ··· 56 57 completely (unless you plan to check further changes) -- you can 57 58 run `make clean-all-asts` to remove them. 58 59 60 60 + [source,sh] 59 61 ---- 60 62 # save pre-change ASTs 61 63 make -j build-all-asts

+7 -1

runtime/HACKING.adoc

reviewed

··· 10 10 11 11 If you want to use the bytecode compiler: 12 12 13 13 + [source,sh] 13 14 ---- 14 15 # build the runtime 15 16 make runtime -j ··· 23 24 24 25 If you want to use the native compiler: 25 26 27 27 + [source,sh] 26 28 ---- 27 29 # build the native runtime 28 30 make runtimeopt -j ··· 45 47 link:https://ocaml.org/manual/runtime.html#s:ocamlrun-options[]. 46 48 You can enable all printing with 47 49 50 50 + [source,sh] 48 51 ---- 49 52 OCAMLRUNPARAM="v=0xffffffff" ./test 50 53 ---- ··· 58 61 Another useful OCAMLRUNPARAM setting is `V=1`, which enables 59 62 additional sanity checks on the heap during major GC cycles. 60 63 64 64 + [source,sh] 61 65 ---- 62 66 OCAMLRUNPARAM="V=1" ./test 63 67 ---- ··· 85 89 `coredumpctl dump` will show you information about the last "core 86 90 dump". 87 91 92 92 + [source,console] 88 93 ---- 89 89 - $ $ coredumpctl dump 94 94 + $ coredumpctl dump 90 95 PID: 678260 (Domain0) 91 96 UID: 1000 (gasche) 92 97 GID: 1000 (gasche) ··· 108 113 109 114 You can get a full backtrace using `echo bt | coredumpctl debug`: 110 115 116 116 + [source,console] 111 117 ---- 112 118 $ echo bt | coredumpctl debug 113 119 [...]

+1 -1

stdlib/HACKING.adoc

reviewed

··· 6 6 Note: All paths are given relative to the root of the repository. 7 7 8 8 First, build the compiler. Run `./configure`, then `make`. See 9 9 - link:../HACKING.adoc[]. 9 9 + xref:../HACKING.adoc[]. 10 10 11 11 To add a new module, you must: 12 12

+2 -2

testsuite/HACKING.adoc

reviewed

··· 12 12 13 13 There are many kind of tests already, so the easiest way to start is 14 14 to extend or copy an existing test. To learn how to write new tests 15 15 - using ocamltest, read [OCAMLTEST.org](../ocamltest/OCAMLTEST.org). 15 15 + using ocamltest, read link:../ocamltest/OCAMLTEST.org[]. 16 16 17 17 Note: in april 2023, the test scripting language has changed: the 18 18 org-mode-based syntax was replaced by at C-like syntax. ocamltest ··· 134 134 | `1` or unset | 2 cores, 2 Gb RAM | 32 or 64 bits 135 135 | `2` | 4 cores, 4 Gb RAM | 64 bits 136 136 | `3` | 8 cores, 8 Gb RAM | 64 bits 137 137 - |===== 137 137 + |==== 138 138 139 139 Tests, then, can check the `OCAML_TEST_SIZE` environment variable and 140 140 increase the number of cores or the amount of memory used. The

+2 -2

typing/HACKING.adoc

reviewed

··· 3 3 inference. Here is a reading list to ease your discovery of the 4 4 typechecker: 5 5 6 6 - http://caml.inria.fr/pub/docs/u3-ocaml/index.html[Using, Understanding, and Unraveling the OCaml Language by Didier R&eacute;my] :: 6 6 + https://caml.inria.fr/pub/docs/u3-ocaml/index.html[_Using, Understanding, and Unraveling the OCaml Language_ by Didier Rémy] :: 7 7 This book provides (among other things) a formal description of parts 8 8 of the core OCaml language, starting with a simple Core ML. 9 9 10 10 - http://okmij.org/ftp/ML/generalization.html[Efficient and Insightful Generalization by Oleg Kiselyov] :: 10 10 + https://okmij.org/ftp/ML/generalization.html[_Efficient and Insightful Generalization_ by Oleg Kiselyov] :: 11 11 This article describes the basis of the type inference algorithm used 12 12 by the OCaml type checker. It is a recommended read if you want to 13 13 understand the type-checker codebase, in particular its handling of

+5 -2

utils/HACKING.adoc

reviewed

··· 19 19 increment the version of every kind of magic number. 20 20 21 21 The process for bootstrapping the compiler is covered in 22 22 - link:../BOOTSTRAP.adoc[BOOTSTRAP.adoc]. There is also a test script in CI which 22 22 + xref:../BOOTSTRAP.adoc[]. There is also a test script in CI which 23 23 demonstrates the process in 24 24 link:../tools/ci/inria/bootstrap/script[tools/ci/inria/bootstrap]. 25 25 ··· 54 54 Since https://github.com/ocaml/ocaml/pull/12652/[PR #12652], simply run 55 55 the following command to bump the magic numbers to version xyz: 56 56 57 57 - tools/bump-magic-numbers xyz 57 57 + [source,sh] 58 58 + ---- 59 59 + tools/bump-magic-numbers xyz 60 60 + ---- 58 61 59 62 Once the bootstrap during which the magic numbers have been bumped 60 63 has been completed, the following files need to be committed: