Merge pull request #797 from crystal-lang/release/1.14

Merge `release/1.14` into `master`

.github/workflows/validate-content.yml

@@ -1,28 +1,37 @@
 name: Validate content
 on:
   push:
+    paths:
+    - docs/syntax_and_semantics/compile_time_flags.md
+    - .github/workflows/validate-content.yml
   pull_request:
     branches: [master, release/*]
+    paths:
+    - docs/syntax_and_semantics/compile_time_flags.md
+    - .github/workflows/validate-content.yml
   schedule:
     - cron: '0 5 * * 1'  # Every Monday 5 AM UTC
 
 jobs:
   validate-flags:
     name: Validate flags
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-latest
-          - os: macos-latest
-          - os: windows-latest
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     steps:
       - name: Download source
         uses: actions/checkout@v4
       - name: Install Crystal
         uses: crystal-lang/install-crystal@v1
         with:
           crystal: nightly
+      - name: Download crystal repo
+        uses: actions/checkout@v4
+        with:
+          repository: crystal-lang/crystal
+          path: crystal
+          # If the PR goes against a release branch, we checkout that same release
+          # branch in the Crystal repo (names are identical).
+          ref: ${{ (startsWith(github.base_ref, 'release/') && github.base_ref) || 'master' }}
       - name: Run test script
         run: scripts/validate-flags.sh
+        env:
+          STDLIB_SRC: ./crystal/src

docs/guides/static_linking.md

@@ -62,9 +62,9 @@ macOS doesn't [officially support fully static linking](https://developer.apple.
 
 Windows doesn't support fully static linking because the Win32 libraries are not available as static libraries.
 
-Currently, static linking is the default mode of linking on Windows, and dynamic linking can be opted in via the `-Dpreview_dll` compile-time flag. In order to distinguish static libraries from DLL import libraries, when the compiler searches for a library `foo.lib` in a given directory, `foo-static.lib` will be attempted first while linking statically, and `foo-dynamic.lib` will be attempted first while linking dynamically. The official Windows packages are distributed with both static and DLL import libraries for all third-party dependencies, except for LLVM.
+In order to distinguish static libraries from DLL import libraries, when the compiler searches for a library `foo.lib` in a given directory, `foo-static.lib` will be attempted first while linking statically, and `foo-dynamic.lib` will be attempted first while linking dynamically. The official Windows MSVC packages are distributed with both static and DLL import libraries for all third-party dependencies, except for LLVM, which is only available as an import library.
 
-Static linking implies using the static version of Microsoft's C runtime library (`/MT`), and dynamic linking implies the dynamic version (`/MD`); extra C libraries should be built with this in mind to avoid linker warnings about mixing CRT versions. There is currently no way to use the dynamic CRT while linking statically.
+Static linking implies using the static version of Microsoft's Universal C Runtime (`/MT`), and dynamic linking implies the dynamic version (`/MD`); extra C libraries should be built with this in mind to avoid linker warnings about mixing CRT versions. There is currently no way to use the dynamic CRT while linking statically.
 
 #### MinGW-w64
 
@@ -124,21 +124,3 @@ In order to link this program statically, we need static versions of these three
 NOTE:
 The `*-alpine` docker images ship with static versions of all libraries used by the standard library.
 If your program links no other libraries then adding the `--static` flag to the build command is all you need to link fully statically.
-
-## Dynamic library lookup
-
-The lookup paths of dynamic libraries at runtime can be controlled by the `CRYSTAL_LIBRARY_RPATH` environment variable during compilation. Currently this is supported on Linux and Windows.
-
-### Linux
-
-If `CRYSTAL_LIBRARY_RPATH` is defined during compilation, it is passed unmodified to the linker via an `-Wl,rpath` option. The exact behavior depends on the linker; usually, this is appended to the ELF executable's `DT_RUNPATH` or `DT_RPATH` dynamic tag entry. The special `$ORIGIN` / `$LIB` / `$PLATFORM` variables might not be supported on all platforms.
-
-### Windows
-
-The standard library supports experimental [DLL delay loading](https://learn.microsoft.com/en-us/cpp/build/reference/linker-support-for-delay-loaded-dlls), and may alter the search order of DLLs by using delay loading.
-
-If a `/DELAYLOAD` linker flag is passed for a given DLL, then the first time an executable loads a symbol from that DLL, it will attempt the semicolon-separated paths in the executable's `CRYSTAL_LIBRARY_RPATH` first, in the order they are declared, before the [default lookup order](https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order#search-order-for-unpackaged-apps). `$ORIGIN` inside `CRYSTAL_LIBRARY_RPATH` expands into the path of the running executable itself. For example, if `CRYSTAL_LIBRARY_RPATH=$ORIGIN\mylibs;C:\bar` during compilation, `--link-flags=/DELAYLOAD:calc.dll` is supplied, and the executable is located at `C:\foo\test.exe`, then the executable searches for `C:\foo\mylibs\calc.dll`, then `C:\bar\calc.dll`, and uses the default order afterwards.
-
-Non-delay-loaded DLLs are loaded immediately upon program startup, and do not respect `CRYSTAL_LIBRARY_RPATH`.
-
-By default, no DLLs are delay-loaded. However, if the `-Dpreview_win32_delay_load` compile-time flag is specified at compilation time, the compiler will detect all DLL dependencies from their import libraries, inserting a `/DELAYLOAD` linker flag per DLL during compilation.

docs/syntax_and_semantics/compile_time_flags.md

@@ -153,9 +153,7 @@ These flags enable or disable compiler features when building a Crystal program.
 |-----------|-------------|
 | `no_number_autocast` | Will not [autocast](autocasting.md#number-autocasting) numeric expressions, only literals |
 | `no_restrictions_augmenter` | Disable enhanced restrictions augmenter. Introduced in 1.5 ([#12103](https://github.com/crystal-lang/crystal/pull/12103)).
-| `preview_dll` | Enable dynamic linking on Windows; experimental |
 | `preview_overload_order` | Enable more robust ordering between def overloads. Introduced in 1.6 ([#10711](https://github.com/crystal-lang/crystal/issues/10711)).
-| `preview_win32_delay_load` | Delay-load all DLLs on Windows; experimental |
 | `strict_multi_assign` | Enable strict semantics for [one-to-many assignment](assignment.md#one-to-many-assignment). Introduced in 1.3.0 ([#11145](https://github.com/crystal-lang/crystal/pull/11145), [#11545](https://github.com/crystal-lang/crystal/pull/11545))
 
 ### Compiler build features

scripts/validate-flags.sh

@@ -1,10 +1,14 @@
-#! /bin/sh
+#! /bin/bash
 
-set -eu
+set -eu -o pipefail
 
 CRYSTAL=${CRYSTAL:-crystal}
-CRYSTAL_PATH="$($CRYSTAL env CRYSTAL_PATH)"
-STDLIB_SRC="${CRYSTAL_PATH#*:}" # stdlib source directory is the last entry in CRYSTAL_PATH
+if [ -z "${STDLIB_SRC-}" ]; then
+  CRYSTAL_PATH="$($CRYSTAL env CRYSTAL_PATH)"
+  STDLIB_SRC="${CRYSTAL_PATH#*:}" # stdlib source directory is the last entry in CRYSTAL_PATH
+fi
+
+echo "Validating flags for stdlib source ${STDLIB_SRC} ($(cat "${STDLIB_SRC}/VERSION"))"
 
 filter_missing() {
   missing=0