From d03bd8477b4be5e88a3e8b895292f9d6d7dfd10d Mon Sep 17 00:00:00 2001 From: Amoghavarsha <35860305+The-Amoghavarsha@users.noreply.github.com> Date: Tue, 1 Oct 2024 12:59:45 +0530 Subject: [PATCH] (docs) Reworked the "Compiling OCaml Projects" Tutorial (#1964) Co-authored-by: Amoghavarsha Co-authored-by: Cuihtlauac Alvarado --- ..._00_using_the_ocaml_compiler_toolchain.md} | 105 +++++++++++++++++- src/ocamlorg_web/lib/redirection.ml | 6 +- 2 files changed, 105 insertions(+), 6 deletions(-) rename data/tutorials/guides/{1wf_00_compiling_ocaml_projects.md => 1wf_00_using_the_ocaml_compiler_toolchain.md} (71%) diff --git a/data/tutorials/guides/1wf_00_compiling_ocaml_projects.md b/data/tutorials/guides/1wf_00_using_the_ocaml_compiler_toolchain.md similarity index 71% rename from data/tutorials/guides/1wf_00_compiling_ocaml_projects.md rename to data/tutorials/guides/1wf_00_using_the_ocaml_compiler_toolchain.md index d498a3f896..1ecc55c889 100644 --- a/data/tutorials/guides/1wf_00_compiling_ocaml_projects.md +++ b/data/tutorials/guides/1wf_00_using_the_ocaml_compiler_toolchain.md @@ -1,8 +1,8 @@ --- -id: compiling-ocaml-projects -title: Compiling OCaml Projects +id: using-the-ocaml-compiler-toolchain +title: Using the OCaml Compiler Toolchain description: > - An introduction to the OCaml compiler tools for building OCaml projects as well as the most common build tools + An introduction to the OCaml compiler tools for building OCaml projects as well as the most common build tools such as Dune category: "Guides" --- @@ -36,7 +36,45 @@ OCaml comes with two compilers: `ocamlc` is the bytecode compiler, and `ocamlopt` is the native code compiler. If you don't know which one to use, use `ocamlopt` since it provides executables that are faster than bytecode. -Let's assume that our program `program` has two source files, +But if you want to try `ocamlc`, you can go ahead and try the following. + +Create a new directory named `hello` and navigate to the directory: + +```shell +$ mkdir hello +$ cd hello +``` +Next, create a file named `hello.ml` and add the following code with your favorite text editor: + +```shell +let () = print_endline "Hello OCaml!" +``` + +Now, we are ready to run the code. Save the file and return to the command line. Let's compile the code: + +```dune +$ ocamlc -o hello hello.ml +``` + +The `-o hello` option tells the compiler to name the output executable as `hello`. The executable `hello` contains compiled OCaml bytecode. In addition, two other files are produced, `hello.cmi` and `hello.cmo`. + +`hello.cmi` contains compiled interface information for OCaml modules. An interface file includes type information and module signatures but doesn't contain the actual code. + +`hello.cmo` contains the compiled bytecode for OCaml modules. Bytecode is an intermediate representation of the code that is executed by the OCaml interpreter or runtime system. + +`Note:` _cmi_ stands for Compiled Module Interface and _cmo_ stands for Compiled Module Object. + +Now let's run the executable and see what happens: + +```shell +$ ./hello +Hello OCaml! +``` +Voilà! It says, `Hello OCaml!`. + +We can change the string or add more content, save the file, recompile, and rerun. + +Moving on, we'll see how to use `ocamlopt`. Let's assume that our program `program` has two source files, `module1.ml` and `module2.ml`. We will compile them to native code, using `ocamlopt`. For now, we also assume that they do not use any other library than the standard library, which is automatically loaded. You @@ -175,6 +213,65 @@ guide](https://dune.readthedocs.io/en/latest/quick-start.html) shows you how to write such description files for more complicated situations, and how to structure, build, and run dune projects. +### Bytecode Using Dune + +Dune is a build system for OCaml projects, and it allows you to configure different modes for building your executables. We will use `(modes byte exe)` stanza in the `dune` file, which will produce both bytecode (interpreted) and native executable versions of the OCaml program. + +Let's create an example project named `myproject`. + +```dune +$ mkdir myproject +$ cd myproject +``` + +Create a `dune-project` file, add the following content. + +```lisp +(lang dune 3.0) +(name myproject) +``` + +Here, 3.0 is the installed version of `Dune`. You can check it by typing `dune --version` on your terminal. And the `name` is the name of the project, i.e., `myproject`. + +Create a `dune` file, add the following content. + +```lisp +(executable + (name main) + (libraries base) + (modes byte exe)) +``` + +As aforementioned, `(modes byte exe)` stanza produces both bytecode (interpreted) and native executable versions of our OCaml program. + +Next, create a `main.ml` file, add the following content. + +```ocaml +let () = print_endline "Hello Dune!" +``` + +Finally, we compile and execute it. + +```shell +$ dune build main.bc +``` + +The `.bc` stands for generic bytecode file, and it can be an executable or library. + +```shell +$ dune exec ./main.bc +Hello Dune! +``` +We can also do that with `.exe`. + +```shell +$ dune build main.exe +``` + +```shell +$ dune exec ./main.exe +Hello Dune! +``` ## Other Build Systems - [OMake](https://github.com/ocaml-omake/omake) Another OCaml build system. diff --git a/src/ocamlorg_web/lib/redirection.ml b/src/ocamlorg_web/lib/redirection.ml index cc870408aa..e24294c4de 100644 --- a/src/ocamlorg_web/lib/redirection.ml +++ b/src/ocamlorg_web/lib/redirection.ml @@ -129,9 +129,11 @@ let from_v2 = ( "/learn/tutorials/comparison_of_standard_containers.zh.html", Url.tutorial "data-structures-comparison" ); ( "/learn/tutorials/compiling_ocaml_projects.ja.html", - Url.tutorial "compiling-ocaml-projects" ); + Url.tutorial "using-the-ocaml-compiler-toolchain" ); + ( Url.tutorial "compiling-ocaml-projects", + Url.tutorial "using-the-ocaml-compiler-toolchain" ); ( "/learn/tutorials/compiling_ocaml_projects.html", - Url.tutorial "compiling-ocaml-projects" ); + Url.tutorial "using-the-ocaml-compiler-toolchain" ); ( "/learn/tutorials/data_types_and_matching.fr.html", Url.tutorial "basic-data-types" ); ( "/learn/tutorials/data_types_and_matching.it.html",