Merge branch 'release/1.14'

crystal-lang · Dec 27, 2024 · 3c73ff6 · 3c73ff6
2 parents d1ce010 + abfc9e5
commit 3c73ff6
Show file tree

Hide file tree

Showing 5 changed files with 139 additions and 92 deletions.
diff --git a/docs/man/required_libraries.md b/docs/man/required_libraries.md
@@ -15,24 +15,24 @@ which may be part of the C library or standalone libraries. On most platforms al
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [glibc][glibc] | standard C library for Linux | [LGPL](https://www.gnu.org/licenses/lgpl-3.0.en.html) |
-| [musl libc][musl-libc] | standard C library for Linux | [MIT](https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT) |
-| [FreeBSD libc][freebsd-libc] | standard C library for FreeBSD | [BSD](https://www.freebsd.org/copyright/freebsd-license/) |
+| [glibc][glibc] | standard C library for Linux <br>**Supported versions:** GNU libc 2.26+ | [LGPL](https://www.gnu.org/licenses/lgpl-3.0.en.html) |
+| [musl libc][musl-libc] | standard C library for Linux <br>**Supported versions:** MUSL libc 1.2+ | [MIT](https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT) |
+| [FreeBSD libc][freebsd-libc] | standard C library for FreeBSD <br>**Supported versions:** 12+ | [BSD](https://www.freebsd.org/copyright/freebsd-license/) |
 | [NetBSD libc][netbsd-libc] | standard C library for NetBSD | [BSD](http://www.netbsd.org/about/redistribution.html) |
-| [OpenBSD libc][openbsd-libc] | standard C library for OpenBSD | [BSD](https://www.openbsd.org/policy.html) |
+| [OpenBSD libc][openbsd-libc] | standard C library for OpenBSD <br>**Supported versions:** 6+ | [BSD](https://www.openbsd.org/policy.html) |
 | [Dragonfly libc][dragonfly-libc] | standard C library for DragonflyBSD | [BSD](https://www.dragonflybsd.org/docs/developer/DragonFly_BSD_License/) |
-| [macOS libsystem][macos-libsystem] | standard C library for macOS | [Apple](https://github.com/apple-oss-distributions/Libsystem/blob/main/APPLE_LICENSE) |
+| [macOS libsystem][macos-libsystem] | standard C library for macOS <br>**Supported versions:** 11+ | [Apple](https://github.com/apple-oss-distributions/Libsystem/blob/main/APPLE_LICENSE) |
 | [MSVCRT][msvcrt] | standard C library for MSVC compiler (Windows) | |
 | [WASI][wasi] | WebAssembly System Interface | [Apache v2 and others](https://github.com/WebAssembly/wasi-libc/blob/main/LICENSE) |
-| [bionic libc][bionic-libc] | C library for Android | [BSD-like](https://android.googlesource.com/platform/bionic/+/refs/heads/master/libc/NOTICE) |
+| [bionic libc][bionic-libc] | C library for Android <br>**Supported versions:** ABI Level 24+ | [BSD-like](https://android.googlesource.com/platform/bionic/+/refs/heads/master/libc/NOTICE) |
 
 ### Other runtime libraries
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [Boehm GC][libgc] | The Boehm-Demers-Weiser conservative garbage collector. Performs automatic memory management. | [MIT-style](https://github.com/ivmai/bdwgc/blob/master/LICENSE)
-| [Libevent][libevent] | An event notification library. Implements concurrency features such as [`Fiber`](https://crystal-lang.org/api/Fiber.html) and the event loop on POSIX platforms. Not used on Windows. | [Modified BSD](https://github.com/libevent/libevent/blob/master/LICENSE)
-| [compiler-rt builtins][compiler-rt] | Provides optimized implementations for low-level routines required by code generation, such as integer multiplication. Several of these routines are ported to Crystal directly. | [MIT / UIUC][compiler-rt]
+| [Boehm GC][libgc] | The Boehm-Demers-Weiser conservative garbage collector. Performs automatic memory management.<br>**Supported versions:** 8.2.0+; earlier versions require a patch for MT support | [MIT-style](https://github.com/ivmai/bdwgc/blob/master/LICENSE) |
+| [Libevent][libevent] | An event notification library. Implements concurrency features such as [`Fiber`](https://crystal-lang.org/api/Fiber.html) and the event loop on POSIX platforms. Not used on Windows. | [Modified BSD](https://github.com/libevent/libevent/blob/master/LICENSE) |
+| [compiler-rt builtins][compiler-rt] | Provides optimized implementations for low-level routines required by code generation, such as integer multiplication. Several of these routines are ported to Crystal directly. | [MIT / UIUC][compiler-rt] |
 
 ## Optional standard library dependencies
 
@@ -45,16 +45,16 @@ PCRE2 support was added in Crystal 1.7 and it's the default since 1.8 (see [Rege
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [PCRE2][libpcre] | Perl Compatible Regular Expressions, version 2. | [BSD](http://www.pcre.org/licence.txt)
-| [PCRE][libpcre] | Perl Compatible Regular Expressions. | [BSD](http://www.pcre.org/licence.txt)
+| [PCRE2][libpcre] | Perl Compatible Regular Expressions, version 2.<br>**Supported versions:** all (recommended: 10.36+) | [BSD](http://www.pcre.org/licence.txt) |
+| [PCRE][libpcre] | Perl Compatible Regular Expressions. | [BSD](http://www.pcre.org/licence.txt) |
 
 ### Big Numbers
 
 Implementations for `Big` types such as [`BigInt`](https://crystal-lang.org/api/BigInt.html).
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [GMP][libgmp] | GNU multiple precision arithmetic library. | [LGPL v3+ / GPL v2+](https://gmplib.org/manual/Copying)
+| [GMP][libgmp] | GNU multiple precision arithmetic library. | [LGPL v3+ / GPL v2+](https://gmplib.org/manual/Copying) |
 | [MPIR][libmpir] | Multiple Precision Integers and Rationals, forked from GMP. Used on Windows MSVC. | [GPL-3.0](https://github.com/wbhart/mpir/blob/master/COPYING) and [LGPL-3.0](https://github.com/wbhart/mpir/blob/master/COPYING.LIB) |
 
 ### Internationalization conversion
@@ -64,7 +64,7 @@ Using a standalone library over the system library implementation can be enforce
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [libiconv][libiconv-gnu] (GNU) | Internationalization conversion library. | [LGPL-3.0](https://www.gnu.org/licenses/lgpl.html)
+| [libiconv][libiconv-gnu] (GNU) | Internationalization conversion library. | [LGPL-3.0](https://www.gnu.org/licenses/lgpl.html) |
 
 ### TLS
 
@@ -74,17 +74,17 @@ Both `OpenSSL` and `LibreSSL` are supported and the bindings automatically detec
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [OpenSSL][openssl] | Implementation of the SSL and TLS protocols | [Apache v2 (3.0+), OpenSSL / SSLeay (1.x)](https://www.openssl.org/source/license.html)
-| [LibreSSL][libressl] | Implementation of the SSL and TLS protocols; forked from OpenSSL in 2014  | [ISC / OpenSSL / SSLeay](https://github.com/libressl-portable/openbsd/blob/master/src/lib/libssl/LICENSE)
+| [OpenSSL][openssl] | Implementation of the SSL and TLS protocols <br>**Supported versions:** 1.1.0+–3.4+ | [Apache v2 (3.0+), OpenSSL / SSLeay (1.x)](https://www.openssl.org/source/license.html) |
+| [LibreSSL][libressl] | Implementation of the SSL and TLS protocols; forked from OpenSSL in 2014 <br>**Supported versions:** 2.0–4.0+ | [ISC / OpenSSL / SSLeay](https://github.com/libressl-portable/openbsd/blob/master/src/lib/libssl/LICENSE) |
 
 ### Other stdlib libraries
 
 | Library | Description | License |
 |---------|-------------|---------|
-| [LibXML2][libxml2] | XML parser developed for the Gnome project. Implements the [`XML`](https://crystal-lang.org/api/XML.html) module. | [MIT](https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/Copyright)
-| [LibYAML][libyaml] | YAML parser and emitter library. Implements the [`YAML`](https://crystal-lang.org/api/YAML.html) module. | [MIT](https://github.com/yaml/libyaml/blob/master/License)
-| [zlib][zlib] | Lossless data compression library. Implements the [`Compress`](https://crystal-lang.org/api/Compress.html) module. May be disabled with the `-Dwithout_zlib` compile-time flag. | [zlib](http://zlib.net/zlib_license.html)
-| [LLVM][libllvm] | Target-independent code generator and optimizer. Implements the [`LLVM`](https://crystal-lang.org/api/LLVM.html) API. | [Apache v2 with LLVM exceptions](https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework)
+| [LibXML2][libxml2] | XML parser developed for the Gnome project. Implements the [`XML`](https://crystal-lang.org/api/XML.html) module. | [MIT](https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/Copyright) |
+| [LibYAML][libyaml] | YAML parser and emitter library. Implements the [`YAML`](https://crystal-lang.org/api/YAML.html) module. | [MIT](https://github.com/yaml/libyaml/blob/master/License) |
+| [zlib][zlib] | Lossless data compression library. Implements the [`Compress`](https://crystal-lang.org/api/Compress.html) module. May be disabled with the `-Dwithout_zlib` compile-time flag. | [zlib](http://zlib.net/zlib_license.html) |
+| [LLVM][libllvm] | Target-independent code generator and optimizer. Implements the [`LLVM`](https://crystal-lang.org/api/LLVM.html) API. <br>**Supported versions:** LLVM 8-19 (aarch64 requires LLVM 13+) | [Apache v2 with LLVM exceptions](https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework) |
 
 ## Compiler dependencies
 
@@ -93,8 +93,8 @@ In addition to the [core runtime dependencies](#core-runtime-dependencies), thes
 | Library | Description | License |
 |---------|-------------|---------|
 | [PCRE2][libpcre] | See above. | |
-| [LLVM][libllvm] | See above. | [Apache v2 with LLVM exceptions](https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework)
-| [libffi][libffi] | Foreign function interface. Used for implementing binary interfaces in the interpreter. May be disabled with the `-Dwithout_interpreter` compile-time flag. | [MIT](https://github.com/libffi/libffi/blob/master/LICENSE)
+| [LLVM][libllvm] | See above. | [Apache v2 with LLVM exceptions](https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework) |
+| [libffi][libffi] | Foreign function interface. Used for implementing binary interfaces in the interpreter. May be disabled with the `-Dwithout_interpreter` compile-time flag. | [MIT](https://github.com/libffi/libffi/blob/master/LICENSE) |
 
 [bionic-libc]: https://android.googlesource.com/platform/bionic/+/refs/heads/master/libc/
 [compiler-rt]: https://compiler-rt.llvm.org/

diff --git a/docs/syntax_and_semantics/compile_time_flags.md b/docs/syntax_and_semantics/compile_time_flags.md
@@ -49,14 +49,14 @@ The target architecture is the first component of the target triple.
 
 | Flag name | Description |
 |-----------|-------------|
-| `aarch64` | AArch64 architecture
-| `avr`     | AVR architecture
-| `arm`     | ARM architecture
-| `i386`    | x86 architecture (32-bit)
-| `wasm32`  | WebAssembly
-| `x86_64`  | x86-64 architecture
-| `bits32` *(derived)*  | 32-bit architecture
-| `bits64` *(derived)*  | 64-bit architecture
+| `aarch64` | AArch64 architecture |
+| `avr`     | AVR architecture |
+| `arm`     | ARM architecture |
+| `i386`    | x86 architecture (32-bit) |
+| `wasm32`  | WebAssembly |
+| `x86_64`  | x86-64 architecture |
+| `bits32` *(derived)*  | 32-bit architecture |
+| `bits64` *(derived)*  | 64-bit architecture |
 
 #### Vendor
 
@@ -65,53 +65,53 @@ so the most common vendor is `unknown`.
 
 | Flag name | Description |
 |-----------|-------------|
-| `macosx`  | Apple
-| `portbld` | FreeBSD variant
-| `unknown` | Unknown vendor
+| `macosx`  | Apple |
+| `portbld` | FreeBSD variant |
+| `unknown` | Unknown vendor |
 
 #### Operating System
 
 The operating system is derived from the third component of a the target triple.
 
 | Flag name | Description |
 |-----------|-------------|
-| `bsd` *(derived)* | BSD family (DragonFlyBSD, FreeBSD, NetBSD, OpenBSD)
-| `darwin`  | Darwin (MacOS)
-| `dragonfly` | DragonFlyBSD
-| `freebsd` | FreeBSD
-| `linux`   | Linux
-| `netbsd`  | NetBSD
-| `openbsd` | OpenBSD
-| `solaris` | Solaris/illumos
-| `unix` *(derived)* | UNIX-like (BSD, Darwin, Linux, Solaris)
-| `windows` | Windows
+| `bsd` *(derived)* | BSD family (DragonFlyBSD, FreeBSD, NetBSD, OpenBSD) |
+| `darwin`  | Darwin (MacOS) |
+| `dragonfly` | DragonFlyBSD |
+| `freebsd` | FreeBSD |
+| `linux`   | Linux |
+| `netbsd`  | NetBSD |
+| `openbsd` | OpenBSD |
+| `solaris` | Solaris/illumos |
+| `unix` *(derived)* | UNIX-like (BSD, Darwin, Linux, Solaris) |
+| `windows` | Windows |
 
 #### ABI
 
 The ABI is derived from the last component of the target triple.
 
 | Flag name | Description |
 |-----------|-------------|
-| `android` | Android (Bionic C runtime)
-| `armhf` *(derived)* | ARM EABI with hard float
-| `gnu`     | GNU
-| `gnueabihf` | GNU EABI with hard float
-| `msvc`    | Microsoft Visual C++
-| `musl`    | musl
-| `wasi`    | Web Assembly System Interface
-| `win32` *(derived)* | Windows API
+| `android` | Android (Bionic C runtime) |
+| `armhf` *(derived)* | ARM EABI with hard float |
+| `gnu`     | GNU |
+| `gnueabihf` | GNU EABI with hard float |
+| `msvc`    | Microsoft Visual C++ |
+| `musl`    | musl |
+| `wasi`    | Web Assembly System Interface |
+| `win32` *(derived)* | Windows API |
 
 ### Compiler options
 
 The compiler sets these flags based on compiler configuration.
 
 | Flag name | Description |
 |-----------|-------------|
-| `release` | Compiler operates in release mode (`--release` or `-O3 --single-module` CLI option)
-| `debug`   | Compiler generates debug symbols (without `--no-debug` CLI option)
-| `static`  | Compiler creates a statically linked executable (`--static` CLI option)
-| `docs`    | Code is processed to generate API docs (`crystal docs` command)
-| `interpreted` | Running in the interpreter (`crystal i`)
+| `release` | Compiler operates in release mode (`--release` or `-O3 --single-module` CLI option) |
+| `debug`   | Compiler generates debug symbols (without `--no-debug` CLI option) |
+| `static`  | Compiler creates a statically linked executable (`--static` CLI option) |
+| `docs`    | Code is processed to generate API docs (`crystal docs` command) |
+| `interpreted` | Running in the interpreter (`crystal i`) |
 
 ## User-provided flags
 
@@ -132,18 +132,18 @@ Crystal program.
 
 | Flag name | Description |
 |-----------|-------------|
-| `gc_none` | Disables garbage collection ([#5314](https://github.com/crystal-lang/crystal/pull/5314))
-| `debug_raise` | Debugging flag for `raise` logic. Prints the backtrace before raising.
-| `preview_mt` | Enables multithreading preview. Introduced in 0.28.0 ([#7546](https://github.com/crystal-lang/crystal/pull/7546))
-| `skip_crystal_compiler_rt` | Exclude Crystal's native `compiler-rt` implementation.
-| `tracing` | Build with support for [runtime tracing](../guides/runtime_tracing.md).
-| `use_libiconv` | Use `libiconv` instead of the `iconv` system library
-| `use_pcre2` | Use PCRE2 as regex engine (instead of legacy PCRE). Introduced in 1.7.0.
-| `use_pcre` | Use PCRE as regex engine (instead of PCRE2). Introduced in 1.8.0.
-| `win7`     | Use Win32 WinNT API for Windows 7
-| `without_iconv` | Do not link `iconv`/`libiconv`
-| `without_openssl` | Build without OpenSSL support
-| `without_zlib` | Build without Zlib support
+| `gc_none` | Disables garbage collection ([#5314](https://github.com/crystal-lang/crystal/pull/5314)) |
+| `debug_raise` | Debugging flag for `raise` logic. Prints the backtrace before raising. |
+| `preview_mt` | Enables multithreading preview. Introduced in 0.28.0 ([#7546](https://github.com/crystal-lang/crystal/pull/7546)) |
+| `skip_crystal_compiler_rt` | Exclude Crystal's native `compiler-rt` implementation. |
+| `tracing` | Build with support for [runtime tracing](../guides/runtime_tracing.md). |
+| `use_libiconv` | Use `libiconv` instead of the `iconv` system library |
+| `use_pcre2` | Use PCRE2 as regex engine (instead of legacy PCRE). Introduced in 1.7.0. |
+| `use_pcre` | Use PCRE as regex engine (instead of PCRE2). Introduced in 1.8.0. |
+| `win7`     | Use Win32 WinNT API for Windows 7 |
+| `without_iconv` | Do not link `iconv`/`libiconv` |
+| `without_openssl` | Build without OpenSSL support |
+| `without_zlib` | Build without Zlib support |
 
 ### Language features
 
@@ -152,9 +152,9 @@ These flags enable or disable language features when building a Crystal program.
 | Flag name | Description |
 |-----------|-------------|
 | `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_overload_order` | Enable more robust ordering between def overloads. Introduced in 1.6 ([#10711](https://github.com/crystal-lang/crystal/issues/10711)).
-| `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))
+| `no_restrictions_augmenter` | Disable enhanced restrictions augmenter. Introduced in 1.5 ([#12103](https://github.com/crystal-lang/crystal/pull/12103)). |
+| `preview_overload_order` | Enable more robust ordering between def overloads. Introduced in 1.6 ([#10711](https://github.com/crystal-lang/crystal/issues/10711)). |
+| `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)) |
 
 ### Codegen features
 
@@ -171,10 +171,10 @@ These flags enable or disable features when building the Crystal compiler.
 
 | Flag name | Description |
 |-----------|-------------|
-| `without_ffi`     | Build the compiler without `libffi`
-| `without_interpreter`  | Build the compiler without interpreter support
-| `without_playground` | Build the compiler without playground (`crystal play`)
-| `i_know_what_im_doing` | Safety guard against involuntarily building the compiler
+| `without_ffi`     | Build the compiler without `libffi` |
+| `without_interpreter`  | Build the compiler without interpreter support |
+| `without_playground` | Build the compiler without playground (`crystal play`) |
+| `i_know_what_im_doing` | Safety guard against involuntarily building the compiler |
 
 ### User code features
 

diff --git a/docs/syntax_and_semantics/macros/hooks.md b/docs/syntax_and_semantics/macros/hooks.md
@@ -103,3 +103,50 @@ Foo.new.bar
 ```
 
 The `print_methods` macro will be run as soon as it is encountered - and will print an empty list as there are no methods defined at that point. Once the second declaration of `Foo` is compiled the `finished` macro will be run, which will print `[bar]`.
+
+Depending on the macro hook used, a hook can either be stacked or overridden.
+
+## Stacking
+
+When stacked, a hook is executed multiple times in its defined context for as many times as the hook is defined. Hooks executed in this way will execute in order of definition. Consider the following example:
+
+```crystal
+# Stack the top-level finished macro
+macro finished
+  {% puts "I will execute!" %}
+end
+
+macro finished
+  {% puts "I will also execute!" %}
+end
+```
+
+In the above example, both `finished` macros will execute. Stacking works for the following hooks: `inherited`, `included`, `extended`, `method_added`, `finished`
+
+## Overriding
+
+A definition of the `method_missing` macro hook overrides any previous definition of this hook in the same context. Only the last defined macro executes. For example:
+
+```crystal
+macro method_missing(name)
+  {% puts "I didnt run! :(" %}
+end
+
+class Example
+  macro method_missing(name)
+    {% puts "I didnt run! :(" %}
+  end
+
+  macro method_missing(name)
+    {% puts "I am the only one that will run!" %}
+  end
+end
+
+macro method_missing(name)
+  {% puts "I am the only one that will run!" %}
+end
+
+Example.new.call_a_missing_method # => I am the only one that will run!
+
+call_a_missing_method # => I am the only one that will run!
+```