+64 -28

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: 53 53 - 54 54 - make bootstrap 65 65 + + 66 66 + [source,sh] 67 67 + ---- 68 68 + make bootstrap 69 69 + ---- 55 70 56 71 == Problems 57 72 ··· 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: 109 109 - 110 110 - make coreall 111 111 - make bootstrap 139 139 + + 140 140 + [source,sh] 141 141 + ---- 142 142 + make coreall 143 143 + make bootstrap 144 144 + ---- 112 145 113 146 == Bootstrap test script 114 147 ··· 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 + ----

+20

HACKING.adoc

reviewed

··· 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 ---- ··· 25 26 26 27 2. Consult link: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 ---- ··· 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 ---- ··· 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 ---- ··· 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 275 opam pin add ocaml-variants git+https://$REPO#branch ··· 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 ··· 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 ··· 331 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 ··· 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 ··· 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 ··· 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 && dune build @libs ··· 629 645 machine, you can use the configuration values and run command taken from 630 646 link:tools/ci/actions/runner.sh[]: 631 647 648 648 + [source,sh] 632 649 ---- 633 650 bash -ex tools/ci/actions/runner.sh configure 634 651 ---- ··· 742 759 branch. In order to use "precheck" to test parallel build on a custom 743 760 branch, add this at the beginning of tools/ci-build: 744 761 762 762 + [source,sh] 745 763 ---- 746 764 OCAML_JOBS=10 747 765 ---- ··· 762 780 763 781 To recreate the `winpthreads` repository from upstream, you can do: 764 782 783 783 + [source,sh] 765 784 ---- 766 785 git clone -o upstream https://git.code.sf.net/p/mingw-w64/mingw-w64 winpthreads 767 786 cd winpthreads ··· 773 792 As subtree splitting is deterministic, repeating these operations later will 774 793 allow to update `master`, for instance by: 775 794 795 795 + [source,sh] 776 796 ---- 777 797 git fetch upstream 778 798 git checkout upstream/master

+66 -29

INSTALL.adoc

reviewed

··· 53 53 54 54 From the top directory, do: 55 55 56 56 - ./configure 56 56 + [source,sh] 57 57 + ---- 58 58 + ./configure 59 59 + ---- 57 60 58 61 This generates the three configuration files `Makefile.config`, 59 62 `runtime/caml/m.h` and `runtime/caml/s.h`. 60 63 61 64 The `configure` script accepts options that can be discovered by running: 62 65 63 63 - ./configure --help 66 66 + [source,sh] 67 67 + ---- 68 68 + ./configure --help 69 69 + ---- 64 70 65 71 Some options or variables like LDLIBS may not be taken into account 66 72 by the OCaml build system at the moment. Please report an issue if you ··· 69 75 Examples: 70 76 71 77 * Standard installation in `/usr/{bin,lib,man}` instead of `/usr/local`: 72 72 - ./configure --prefix=/usr 73 73 - 78 78 + + 79 79 + [source,sh] 80 80 + ---- 81 81 + ./configure --prefix=/usr 82 82 + ---- 74 83 75 84 * 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 85 85 + + 86 86 + [source,sh] 87 87 + ---- 88 88 + ./configure --build=x86_64-pc-linux-gnu --host=i686-linux-gnu 89 89 + ---- 78 90 79 91 * For AIX 7.x with the IBM compiler `xlc`: 80 80 - 81 81 - ./configure CC=xlc 92 92 + + 93 93 + [source,sh] 94 94 + ---- 95 95 + ./configure CC=xlc 96 96 + ---- 82 97 + 83 98 By default, build is 32-bit. For 64-bit build, please set environment variable `OBJECT_MODE=64` 84 99 for _both_ `configure` and `make world` phases. Note, if this variable is set for only one phase, 85 100 your build will break (`ocamlrun` segfaults). 86 86 - + 101 101 + 87 102 * For Solaris/Illumos on SPARC machines with Sun PRO compiler only 64-bit 88 103 bytecode target is supported (32-bit fails due to alignment issues; the optimization 89 104 is preset to `-O4` for inlining): 90 90 - 91 91 - ./configure CC="cc -m64" 105 105 + + 106 106 + [source,sh] 107 107 + ---- 108 108 + ./configure CC="cc -m64" 109 109 + ---- 92 110 + 93 111 If something goes wrong during the automatic configuration, or if the generated 94 112 files cause errors later on, then look at the template files: 95 95 - 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 113 113 + + 114 114 + ---- 115 115 + Makefile.config.in 116 116 + Makefile.build_config.in 117 117 + runtime/caml/m.h.in 118 118 + runtime/caml/s.h.in 119 119 + ---- 100 120 + 101 121 for guidance on how to edit the generated files by hand. 102 122 103 123 == Building the compiler 104 124 105 125 From the top directory, do: 106 106 - 107 107 - make 126 126 + [source,sh] 127 127 + ---- 128 128 + make 129 129 + ---- 108 130 109 131 This builds the OCaml compiler for the first time. This phase is 110 132 fairly verbose; consider redirecting the output to a file: 111 133 112 112 - make > make.log 2>&1 # in sh 113 113 - make >& make.log # in csh 134 134 + [source,sh] 135 135 + ---- 136 136 + make > make.log 2>&1 # in sh 137 137 + make >& make.log # in csh 138 138 + ---- 114 139 115 140 == (Optional) Running the testsuite 116 141 117 142 To be sure everything works well, you can run the test suite 118 143 that comes with the compiler. To do so, do: 119 144 120 120 - make tests 145 145 + [source,sh] 146 146 + ---- 147 147 + make tests 148 148 + ---- 121 149 122 150 == Installing the compiler 123 151 ··· 143 171 144 172 From the top directory, become superuser and do: 145 173 146 146 - make install 174 174 + [source,sh] 175 175 + ---- 176 176 + make install 177 177 + ---- 147 178 148 179 Installation is complete. Time to clean up. From the toplevel directory, 149 180 do: 150 181 151 151 - make clean 182 182 + [source,sh] 183 183 + ---- 184 184 + make clean 185 185 + ---- 152 186 153 187 After installation, do *not* strip the `ocamldebug` executables. 154 188 This is a mixed-mode executable (containing both compiled C ··· 217 251 setting the `TARGET_LIBDIR` variable. For instance, with the GCC MinGW cross 218 252 compiler installed, one may use: 219 253 220 220 - .... 254 254 + [source,sh] 255 255 + ---- 221 256 ./configure --prefix=$PWD/cross --target=x86_64-w64-mingw32 TARGET_LIBDIR='C:\somedir' ... 222 257 make crossopt -j 223 258 make installcross 224 224 - .... 259 259 + ---- 225 260 226 261 Notes: 227 262 ··· 239 274 If you have built a cross compiler to a Unix target, you can simply run as 240 275 usual: 241 276 242 242 - .... 277 277 + [source,sh] 278 278 + ---- 243 279 cross/bin/ocamlopt.opt -o test test.ml 244 244 - .... 280 280 + ---- 245 281 246 282 If you have built a Unix-to-Windows cross compiler, you must first make sure 247 283 that `ocamlopt` can find the `flexlink` executable in `$PATH` when it needs to 248 284 link. Bootstrapping `flexdll` builds a `flexlink.exe` (note the `.exe`!), so you 249 285 can: 250 286 251 251 - .... 287 287 + [source,sh] 288 288 + ---- 252 289 ln -s flexlink.exe cross/bin/flexlink 253 290 (export PATH="$PWD/cross/bin:$PATH"; ocamlopt.opt.exe -o test.exe test.ml) 254 254 - .... 291 291 + ---- 255 292 256 293 or any other possibility to make sure `ocamlopt` can invoke `flexlink`.

+53 -17

README.win32.adoc

reviewed

··· 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 ··· 211 229 212 230 For 64-bit, now run: 213 231 214 214 - ./configure --build=x86_64-pc-cygwin --host=x86_64-w64-mingw32 232 232 + [source,sh] 233 233 + ---- 234 234 + ./configure --build=x86_64-pc-cygwin --host=x86_64-w64-mingw32 235 235 + ---- 215 236 216 237 or, for 32-bit: 217 238 218 218 - ./configure --build=x86_64-pc-cygwin --host=i686-w64-mingw32 239 239 + [source,sh] 240 240 + ---- 241 241 + ./configure --build=x86_64-pc-cygwin --host=i686-w64-mingw32 242 242 + ---- 219 243 220 244 Finally, use `make` to build the system, e.g. 221 245 222 222 - make 223 223 - make install 246 246 + [source,sh] 247 247 + ---- 248 248 + make 249 249 + make install 250 250 + ---- 224 251 225 252 After installing, you will need to ensure that `ocamlopt` (or `ocamlc -custom`) 226 253 can access the C compiler. You can do this either by using OCaml from Cygwin's ··· 249 276 https://github.com/ocaml/flexdll/releases 250 277 * Cloning the git repository by running: 251 278 + 252 252 - git clone https://github.com/ocaml/flexdll.git 279 279 + [source,sh] 280 280 + ---- 281 281 + git clone https://github.com/ocaml/flexdll.git 282 282 + ---- 253 283 254 284 * If you are compiling from a git clone of the OCaml repository, instead of 255 285 using a sources tarball, you can run: 256 286 + 257 257 - git submodule update --init 287 287 + [source,sh] 288 288 + ---- 289 289 + git submodule update --init 290 290 + ---- 258 291 259 292 OCaml is then compiled normally for the port you require. 260 293 261 261 - make 262 262 - make install 294 294 + [source,sh] 295 295 + ---- 296 296 + make 297 297 + make install 298 298 + ---- 263 299 264 300 * `make install` will install FlexDLL by placing `flexlink.exe` 265 301 (and the default manifest file for the Microsoft port) in `bin/` and the

+2

parsing/HACKING.adoc

reviewed

··· 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 [...]

+4 -1

utils/HACKING.adoc

reviewed

··· 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: