Merge branch 'ocaml:main' into main

Author: richardhuxton

.github/workflows/debug-ci.yml

@@ -20,10 +20,10 @@ jobs:
 
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Use OCaml ${{ matrix.ocaml-compiler }}
-        uses: ocaml/setup-ocaml@v2
+        uses: ocaml/setup-ocaml@v3
         with:
           ocaml-compiler: ${{ matrix.ocaml-compiler }}
           dune-cache: ${{ matrix.os != 'macos-latest' }}

data/changelog/dune/2024-06-17-dune.3.16.0.md

@@ -0,0 +1,75 @@
+---
+title: Dune 3.16.0
+tags: [dune, platform]
+changelog: |
+   ### Added
+   
+   - Allow libraries with the same `(name ..)` in projects as long as they don't
+     conflict during resolution (via `enabled_if`). (#10307, @anmonteiro,
+     @jchavarri)
+   
+   - `dune describe pp` now finds the exact module and the stanza it belongs to,
+     instead of guessing the name of the preprocessed file. (#10321, @anmonteiro)
+   
+   - Print the result of `dune describe pp` with the respective dialect printer.
+     (#10322, @anmonteiro)
+   
+   - Add new flag `--context` to `dune ocaml-merlin`, which allows to select a
+     Dune context when requesting Merlin config. Add `dune describe contexts`
+     subcommand. Introduce a field `generate_merlin_rules` for contexts declared
+     in the workspace, that allows to optionally produce Merlin rules for other
+     contexts besides the one selected for Merlin (#10324, @jchavarri)
+   
+   - Melange: add include paths for private library `.cmj` files during JS
+     emission. (#10416, @anmonteiro)
+   
+   - `dune ocaml-merlin`: communicate additional directives `SOURCE_ROOT`,
+     `UNIT_NAME` (the actual name with wrapping) and `INDEX` with the paths to the
+     index(es). (#10422, @voodoos)
+   
+   - Add a new alias `@ocaml-index` that uses the `ocaml-index` binary to generate
+     indexes that can be read by tools such as Merlin to provide project-wide
+     references search. (#10422, @voodoos)
+   
+   - Merlin: add optional `(merlin_reader CMD)` construct to `(dialect)` stanza to
+     configure a Merlin reader (#8567, @andreypopp)
+   
+   ### Changed
+   
+   - Melange: treat private libraries with `(package ..)` as public libraries,
+     fixing an issue where `import` paths were wrongly emitted. (#10415,
+     @anmonteiro)
+   
+   - Install `.glob` files for Coq theories too (#10602, @ejgallego)
+   
+   ### Fixed
+   
+   - Don't try to document nonexistent libraries in doc-new target (#10319, fixes
+     #10056, @jonludlam)
+   
+   - Make `dune-site`'s `load_all` function look for `META` files so that it
+     doesn't fail on empty directories in the plugin directory (#10458, fixes
+     #10457, @shym)
+   
+   - Fix incorrect warning for libraries defined inside nonexistant directories
+     using `(subdir ..)` and used by executables using `dune-build-info` (#10525,
+     @rgrinberg)
+   
+   - Don't try to take build lock when running `coq top --no-build` (#10547, fixes
+     #7671, @lzy0505)
+   
+   - Make sure to truncate Dune's lock file after locking and unlocking so that
+     users cannot observe incorrect PID's (#10575, @rgrinberg)
+   
+   - MDX: link MDX binary with `byte_complete`. This fixes `(libraries)` with
+     foreign archives on Linux. (#10586, fixes #10582, @anmonteiro)
+   
+   - Virtual libraries: fix an issue where linking an executable involving several
+     virtual libries would cause an error. (#10581, fixes #10460, @rgrinberg)
+---
+
+We're happy to announce the release of Dune 3.16.0.
+
+Among the list of chances, this release contains improvements to Melange
+support and a way to look for references in a whole project using Merlin and
+OCaml LSP.

data/cookbook/compress-single-file-gzip/00-camlzip.ml

@@ -0,0 +1,28 @@
+---
+packages:
+- name: "camlzip"
+  tested_version: "1.11"
+  used_libraries:
+  - camlzip
+---
+
+(* We open both files (`source` with `In_channel.open_bin` and `dest` with `Gzip.open_out`)
+   and transfer bytes through a bytes buffer. *)
+
+let buffer_size = 4096
+
+let gzip source dest =
+  let gz_file = Gzip.open_out ~level:9 dest in
+  let buffer = Bytes.make buffer_size '*' in
+  let ic = In_channel.open_bin source in
+  let rec aux () =
+    let len = In_channel.input ic buffer 0 buffer_size in
+    if len <> 0 then
+      begin
+        Gzip.output gz_file buffer 0 len;
+        aux ()
+      end
+  in
+  aux ();
+  Gzip.close_out gz_file;
+  In_channel.close ic

data/cookbook/create-zip-archive/00-camlzip.ml

@@ -0,0 +1,38 @@
+---
+packages:
+- name: "camlzip"
+  tested_version: "1.11"
+  used_libraries:
+  - camlzip
+---
+
+(*
+  The [Zip](/p/camlzip/latest/doc/Zip/index.html) module doesn't provide a function that works on a directory.
+
+  Thus, we write a helper-function to traverse the file-system.
+  Here the given function `f` is called for each regular file with its name as a parameter.
+  
+   *)
+let rec traverse_fs f directory =
+  if Sys.is_directory directory then
+    Sys.readdir directory
+    |> Array.iter
+         (fun entry ->
+            traverse
+              f (directory ^ "/" ^ entry))
+  else
+    f directory
+
+
+(* First, we open the ZIP file for writing. *)
+let zip zip_filename directory_name =
+  let zip_file = Zip.open_out zip_filename in
+
+(* Then, we use `Zip.copy_file_to_entry` to add every file in the directory to the ZIP file. *)
+  traverse_fs
+    (fun name ->
+      Zip.copy_file_to_entry name zip_file name)
+    directory_name;
+(* To finalize the archive, we close the ZIP file. *)
+  Zip.close_out zip_file
+

data/cookbook/decompress-single-file-gzip/00-camlzip.ml

@@ -0,0 +1,28 @@
+---
+packages:
+- name: "camlzip"
+  tested_version: "1.11"
+  used_libraries:
+  - camlzip
+---
+
+(* To decompress a single file using the [Gzip](/p/camlzip/latest/doc/Gzip/index.html) module from `camlzip`,
+   we open both files (`source` with `Gzip.open_in` and `dest` with `Out_channel.open_bin`) and transfer bytes through a bytes buffer. *)
+
+let buffer_size = 4096
+
+let gunzip source dest =
+  let gz_file = Gzip.open_in source in
+  let buffer = Bytes.make buffer_size '*' in
+  let oc = Out_channel.open_bin dest in
+  let rec aux () =
+    let len = Gzip.input gz_file buffer 0 buffer_size in
+    if len <> 0 then
+      begin
+        Out_channel.output oc buffer 0 len;
+        aux ()
+      end
+  in
+  aux ();
+  Gzip.close_in gz_file;
+  Out_channel.close oc

data/cookbook/decompress-zip-archive/00-camlzip.ml

@@ -0,0 +1,49 @@
+---
+packages:
+- name: "camlzip"
+  tested_version: "1.11"
+  used_libraries:
+  - camlzip
+---
+
+(* When unzipping a file from a ZIP archive, we need to create the directory
+   it is contained in, if it doesn't exist yet.  *)
+let create_dir_if_not_exists filename =
+  let rec aux_ensure base l =
+    if not (Sys.file_exists base) then
+      Sys.mkdir base 0o755
+    else
+      if not (Sys.is_directory base) then
+        failwith "Error, file exists instead of a directory";
+    match l with
+    | [] -> failwith "Should not happen"
+    | [ _filename ] -> ()
+    | directory :: l' -> aux_ensure (base ^ "/" ^ directory) l'
+  in
+  match String.split_on_char '/' filename with
+  | [ ] -> failwith "Should not happen (null filename)"
+  | [ _filename ] -> ()
+  | directory :: l -> aux_ensure directory l
+
+(* Open the ZIP file for reading. *)
+let unzip zip_filename =
+  let zip = Zip.open_in zip_filename in
+
+(* Iterate over all entries within the ZIP file. *)
+  let entries = Zip.entries zip in
+  entries
+  |> List.iter (fun entry ->
+         Printf.printf "%s\n" entry.Zip.filename;
+         create_dir_if_not_exists entry.Zip.filename;
+(* If the entry is a directory, just create the directory. *)
+         if entry.Zip.is_directory then
+           Sys.mkdir entry.Zip.filename 0o755
+
+(* If the entry is a regular file, decompress it. *)
+         else
+           Zip.copy_entry_to_file
+             zip
+             entry
+             entry.Zip.filename);
+(* Finally, close the ZIP file. *)
+  Zip.close_in zip

data/cookbook/tasks.yml

@@ -6,7 +6,7 @@ categories:
   - title: Using the ANSI Terminal
     slug: using-the-ansi-terminal
     description: >
-      Use ANSI escape codes for cursor location, font and colour in video text
+      Use ANSI escape codes for cursor location, font, and colour in video text
       terminal emulators.
 - title: Compilation & Linking
   tasks:
@@ -18,8 +18,14 @@ categories:
       C library, using the OCaml foreign function interface.
 - title: Compression
   tasks:
-  - title: Read a gzip compressed text file
-    slug: read-gzip-text-file
+  - title: Decompress a Single File Compressed With GZIP
+    slug: decompress-single-file-gzip
+  - title: Compress a Single File with GZIP
+    slug: compress-single-file-gzip
+  - title: Decompress a ZIP Archive Containing Multiple Files
+    slug: decompress-zip-archive
+  - title: Create a ZIP Archive Containing Multiple Files
+    slug: create-zip-archive
   - title: Decompressing a Tarball
     slug: decompressing-a-tarball
   - title: Compress a Directory Into a Tarball
@@ -40,9 +46,9 @@ categories:
   tasks:
   - title: Calculate the SHA-256 Digest of a File
     slug: calculate-sha-256-digest-of-file
-  - title: Sign and Verify a Message with an HMAC Digest
+  - title: Sign and Verify a Message With an HMAC Digest
     slug: sign-and-verify-hmac-digest
-  - title: Salt and Hash a Password with PBKDF2
+  - title: Salt and Hash a Password With PBKDF2
     slug: salt-and-hash-password-with-pkgdf2
 - title: Data Structures & Algorithms
   subcategories:
@@ -113,15 +119,15 @@ categories:
     slug: debug-print-a-value
   - title: Log a Debug / Error Message to Stdout / Stderr
     slug: log-debug-error-message
-  - title: Log to the UNIX Syslog
+  - title: Log to the Unix Syslog
     slug: log-to-unix-syslog
 - title: Encoding
   tasks:
   - title: URL- / Percent-Encode a String
     slug: url-percent-encode-string
   - title: Encode a String as application/x-www-form-urlencoded
     slug: encode-x-www-form-urlencoded
-  - title: Encode and Decode Bytestrings from Hex-Strings
+  - title: Encode and Decode Bytestrings From Hex-Strings
     slug: encode-decode-hex
   - title: Encode and Decode Base64
     slug: encode-decode-base64
@@ -170,13 +176,13 @@ categories:
 #    slug: trigger-minor-major-collection
 - title: Random Values
   tasks:
-  - title: Generate Random `int`, `float` and `char`
+  - title: Generate Random `int`, `float`, and `char`
     slug: generate-random-values
 - title: Mathematics
   subcategories:
   - title: Vector & Matrix Operations
     tasks:
-    - title: Normalize a Vector
+    - title: Normalise a Vector
       slug: normalize-vector
     - title: Matrix Addition and Multiplication
       slug: matrix-addition-multiplication
@@ -214,7 +220,7 @@ categories:
       slug: regex-validate-email
     - title: Extract Phone Numbers from Text
       slug: regex-extract-phone-numbers
-    - title: Replace All Occurrences of a Text Pattern with Another Pattern
+    - title: Replace All Occurrences of a Text Pattern With Another Pattern
       slug: regex-replace-pattern
 - title: Web Programming
   subcategories:
@@ -224,37 +230,39 @@ categories:
       slug: make-http-get-request
       description: >
         Make an HTTP GET request, process response code, follow redirects
-    - title: Make a HTTP GET Request with Basic Authentication
+    - title: Make a HTTP GET Request With Basic Authentication
       slug: make-http-get-basic-auth
     - title: Download a File to a Temporary Directory
       slug: download-file-to-temporary-dir
-    - title: Make a Partial Download with HTTP Range Header
+    - title: Make a Partial Download With HTTP Range Header
       slug: make-partial-download-with-http-range-header
-  - title: Dealing with HTML
+  - title: Dealing With HTML
     tasks:
-    - title: Render a HTML Template
+    - title: Render an HTML Template
       slug: render-html-template
-    - title: Extract all Links from a HTML String
+    - title: Extract All Links From an HTML String
       slug: extract-links-from-html
     - title: Check a Webpage for Broken Links
       slug: check-webpage-for-broken-links
   - title: Running a Web Server
     tasks:
-    - title: Start a Web Server with a Hello World Endpoint
+    - title: Start a Web Server With a 'Hello World' Endpoint
       slug: start-a-web-server-hello-world
-    - title: Start a Web Server that Serves a HTML Template
+    - title: Start a Web Server That Serves an HTML Template
       slug: start-a-web-server-html-template
     - title: Use Basic Authentication to Secure a Route
       slug: use-basic-auth-on-web-server
   - title: Media Types (MIME)
     tasks:
-    - title: Get MIME Type from String
+    - title: Get MIME Type From String
       slug: get-mime-type-from-string
-    - title: Get MIME Type from Filename
+    - title: Get MIME Type From Filename
       slug: get-mime-type-from-filename
-    - title: Parse MIME Type of a HTTP Response
+    - title: Parse MIME Type of an HTTP Response
       slug: parse-mime-type-of-http-response
-  - title: URL and URI processing
+  - title: URL and URI Processing
     tasks:
-    - title: Parse a URL from String And Access Individual Parts
-      slug: parse-url-from-string
+    - title: Parse a URI from String and Access Individual Parts
+      slug: uri-parsing
+    - title: Encode a URI to String
+      slug: uri-encoding