From ff32978f5bf2a9b4b39b04185e4bcabc79db58fa Mon Sep 17 00:00:00 2001 From: Roger Pack Date: Sat, 27 Apr 2024 03:25:15 -0600 Subject: [PATCH 1/4] Add reference to compiler manual in Testing Guide (#758) --- docs/guides/testing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/testing.md b/docs/guides/testing.md index d16ebf2ae..43d9d61d1 100644 --- a/docs/guides/testing.md +++ b/docs/guides/testing.md @@ -196,6 +196,8 @@ crystal spec --tag 'fast' crystal spec --tag '~slow' ``` +There are additional options for running specs by name, adjusting output formats, doing dry-runs, etc, see [Using the compiler](../man/crystal/README.md#crystal-spec). + ## Spec helper Many projects use a custom spec helper file, usually named `spec/spec_helper.cr`. From 2434a0b9f9b5f113fef4d389a37f6db6ac766c30 Mon Sep 17 00:00:00 2001 From: Roger Pack Date: Sun, 28 Apr 2024 13:31:00 -0600 Subject: [PATCH 2/4] Update spec parameters (#759) --- docs/man/crystal/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/man/crystal/README.md b/docs/man/crystal/README.md index 9cb98ddbb..15666f345 100644 --- a/docs/man/crystal/README.md +++ b/docs/man/crystal/README.md @@ -291,14 +291,15 @@ $ crystal env CRYSTAL_VERSION The `crystal spec` command compiles and runs a Crystal spec suite. ``` -crystal spec [] [...] [-- []] +crystal spec [] [[:line] | ]... [-- []] ``` All `files` arguments are concatenated into a single Crystal source. If an argument points to a folder, all spec -files inside that folder are appended. If no `files` argument is provided, the default is `./spec`. A filename can be suffixed by `:` -and a line number, providing this location to the `--location` runner option (see below). +files inside that folder (and its recursive subfolders) named `*_spec.cr` are appended. +If no `files` argument is provided, the default is the `./spec` folder. +A filename can be suffixed by `:` and a line number, providing this location to the `--location` runner option (see below). -Run `crystal spec --options` for available options. +Run `crystal spec --options` for available preceding options. **Runner options:** @@ -316,7 +317,7 @@ the other arguments by a double dash (`--`). * `--dry-run`: Passes all tests without actually executing them. * `--help`, `-h`: Prints help and exits. -The following options can be combined to filter the list of specs to run. +The following runner options can be combined to filter the list of specs to run. * `--example `, `-e `: Runs examples whose full nested names include ``. * `--line `, `-l `: Runs examples whose line matches ``. From 68669b300c1eab3bfdaec89b1a8fef4705af4e46 Mon Sep 17 00:00:00 2001 From: Quinton Miller Date: Tue, 30 Apr 2024 16:02:07 +0800 Subject: [PATCH 3/4] Document `asm` (#746) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Oleh Prypin Co-authored-by: Johannes Müller --- devenv.lock | 62 ++++++++++++------- docs/SUMMARY.md | 1 + docs/syntax_and_semantics/asm.md | 38 ++++++++++++ docs/syntax_and_semantics/documenting_code.md | 2 +- mkdocs.yml | 11 ++-- requirements.in | 3 +- requirements.txt | 56 +++++++++-------- 7 files changed, 116 insertions(+), 57 deletions(-) create mode 100644 docs/syntax_and_semantics/asm.md diff --git a/devenv.lock b/devenv.lock index a8350a66f..3305f444a 100644 --- a/devenv.lock +++ b/devenv.lock @@ -3,11 +3,11 @@ "devenv": { "locked": { "dir": "src/modules", - "lastModified": 1683288106, - "narHash": "sha256-8/yuP6gWLhK8tRCtyqY5QnTq9GF7pCWpZyyZ08lXFwM=", + "lastModified": 1713882078, "owner": "cachix", "repo": "devenv", - "rev": "c4006ccba1b3e4533de462cee5933e0ccf5f1d6a", + "rev": "9c7ac1b365c2f78614f47ed9f5adfff894181fa4", + "treeHash": "610a66d5157278261ffbd0442cc7847e6d63d2fd", "type": "github" }, "original": { @@ -20,11 +20,11 @@ "flake-compat": { "flake": false, "locked": { - "lastModified": 1673956053, - "narHash": "sha256-4gtG9iQuiKITOjNQQeQIpoIB6b16fm+504Ch3sNKLd8=", + "lastModified": 1696426674, "owner": "edolstra", "repo": "flake-compat", - "rev": "35bb57c0c8d8b62bbfd284272c928ceb64ddbde9", + "rev": "0f9255e01c2351cc7d116c072cb317785dd33b33", + "treeHash": "2addb7b71a20a25ea74feeaf5c2f6a6b30898ecb", "type": "github" }, "original": { @@ -34,12 +34,15 @@ } }, "flake-utils": { + "inputs": { + "systems": "systems" + }, "locked": { - "lastModified": 1667395993, - "narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=", + "lastModified": 1710146030, "owner": "numtide", "repo": "flake-utils", - "rev": "5aed5285a952e0b949eb3ba02c12fa4fcfef535f", + "rev": "b1d9ab70662946ef0850d488da1c9019f3a9752a", + "treeHash": "bd263f021e345cb4a39d80c126ab650bebc3c10c", "type": "github" }, "original": { @@ -56,11 +59,11 @@ ] }, "locked": { - "lastModified": 1660459072, - "narHash": "sha256-8DFJjXG8zqoONA1vXtgeKXy68KdJL5UaXR8NtVMUbx8=", + "lastModified": 1709087332, "owner": "hercules-ci", "repo": "gitignore.nix", - "rev": "a20de23b925fd8264fd7fad6454652e142fd7f73", + "rev": "637db329424fd7e46cf4185293b9cc8c88c95394", + "treeHash": "ca14199cabdfe1a06a7b1654c76ed49100a689f9", "type": "github" }, "original": { @@ -71,11 +74,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1683475240, - "narHash": "sha256-sy6MYoCaIZsOenYplbzVXI4Ce9Bp/vIOpuFa97+a6wc=", + "lastModified": 1713805509, "owner": "NixOS", "repo": "nixpkgs", - "rev": "e040aab15638aaf8d0786894851a2b1ca09a7baf", + "rev": "1e1dc66fe68972a76679644a5577828b6a7e8be4", + "treeHash": "45178d59be92731d710aea19878b2f10c925a040", "type": "github" }, "original": { @@ -87,16 +90,16 @@ }, "nixpkgs-stable": { "locked": { - "lastModified": 1678872516, - "narHash": "sha256-/E1YwtMtFAu2KUQKV/1+KFuReYPANM2Rzehk84VxVoc=", + "lastModified": 1713725259, "owner": "NixOS", "repo": "nixpkgs", - "rev": "9b8e5abb18324c7fe9f07cb100c3cd4a29cda8b8", + "rev": "a5e4bbcb4780c63c79c87d29ea409abf097de3f7", + "treeHash": "d71e381aa8a18139cbba1b0bae4338a2b78108df", "type": "github" }, "original": { "owner": "NixOS", - "ref": "nixos-22.11", + "ref": "nixos-23.11", "repo": "nixpkgs", "type": "github" } @@ -112,11 +115,11 @@ "nixpkgs-stable": "nixpkgs-stable" }, "locked": { - "lastModified": 1682596858, - "narHash": "sha256-Hf9XVpqaGqe/4oDGr30W8HlsWvJXtMsEPHDqHZA6dDg=", + "lastModified": 1713775815, "owner": "cachix", "repo": "pre-commit-hooks.nix", - "rev": "fb58866e20af98779017134319b5663b8215d912", + "rev": "2ac4dcbf55ed43f3be0bae15e181f08a57af24a4", + "treeHash": "419ef022a9c8ad014d76c605ef29c0e2d7fc07a0", "type": "github" }, "original": { @@ -131,6 +134,21 @@ "nixpkgs": "nixpkgs", "pre-commit-hooks": "pre-commit-hooks" } + }, + "systems": { + "locked": { + "lastModified": 1681028828, + "owner": "nix-systems", + "repo": "default", + "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", + "treeHash": "cce81f2a0f0743b2eb61bc2eb6c7adbe2f2c6beb", + "type": "github" + }, + "original": { + "owner": "nix-systems", + "repo": "default", + "type": "github" + } } }, "root": "root", diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index cb0cb4d9f..485b5ae68 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -100,6 +100,7 @@ * [instance_alignof](syntax_and_semantics/instance_alignof.md) * [offsetof](syntax_and_semantics/offsetof.md) * [Uninitialized variable declaration](syntax_and_semantics/declare_var.md) + * [asm](syntax_and_semantics/asm.md) * [Compile-time flags](syntax_and_semantics/compile_time_flags.md) * [Cross-compilation](syntax_and_semantics/cross-compilation.md) * [Platform Support](syntax_and_semantics/platform_support.md) diff --git a/docs/syntax_and_semantics/asm.md b/docs/syntax_and_semantics/asm.md new file mode 100644 index 000000000..24e3aad10 --- /dev/null +++ b/docs/syntax_and_semantics/asm.md @@ -0,0 +1,38 @@ +# asm + +The `asm` keyword can be used to insert inline assembly, which is needed for a very small set of features such as fiber switching and system calls: + +```crystal +# x86-64 targets only +dst = 0 +asm("mov $$1234, $0" : "=r"(dst)) +dst # => 1234 +``` + +An `asm` expression consists of up to 5 colon-separated sections, and components inside each section are separated by commas. For example: + +```crystal +asm( + # the assembly template string, following the + # syntax for LLVM's integrated assembler + "nop" : + # output operands + "=r"(foo), "=r"(bar) : + # input operands + "r"(1), "r"(baz) : + # names of clobbered registers + "eax", "memory" : + # optional flags, corresponding to the LLVM IR + # sideeffect / alignstack / inteldialect / unwind attributes + "volatile", "alignstack", "intel", "unwind" +) +``` + +Only the template string is mandatory, all other sections can be empty or omitted: + +```crystal +asm("nop") +asm("nop" :: "b"(1), "c"(2)) # output operands are empty +``` + +For more details, refer to the [LLVM documentation's section on inline assembler expressions](https://llvm.org/docs/LangRef.html#inline-assembler-expressions). diff --git a/docs/syntax_and_semantics/documenting_code.md b/docs/syntax_and_semantics/documenting_code.md index 503eebe72..52f203a1d 100644 --- a/docs/syntax_and_semantics/documenting_code.md +++ b/docs/syntax_and_semantics/documenting_code.md @@ -206,7 +206,7 @@ Following comment lines can be used for internal documentation. ### `inherit` -See [*Inheriting Documentation*](#Inheriting Documentation). +See [*Inheriting Documentation*](#inheriting-documentation). ## Inheriting Documentation diff --git a/mkdocs.yml b/mkdocs.yml index dc4172560..320e61e14 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,7 @@ validation: omitted_files: warn absolute_links: warn unrecognized_links: warn + anchors: warn exclude_docs: | SUMMARY.md @@ -80,9 +81,9 @@ plugins: validators: - crystal tool format --check - - crystal build --no-codegen $< - - mkdocs-simple-hooks: - hooks: - on_page_markdown: 'hooks:on_page_markdown' + +hooks: + - hooks.py markdown_extensions: - admonition @@ -91,8 +92,8 @@ markdown_extensions: - pymdownx.betterem: smart_enable: all - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight - pymdownx.magiclink - pymdownx.superfences diff --git a/requirements.in b/requirements.in index feb9aaf0b..0531a6117 100644 --- a/requirements.in +++ b/requirements.in @@ -1,8 +1,7 @@ -mkdocs>=1.5.0 +mkdocs>=1.6.0 markdown-callouts>=0.2.0 mkdocs-material>=8.0.5 mkdocs-literate-nav>=0.2 mkdocs-section-index>=0.2.3 mkdocs-redirects>=1.0.4 mkdocs-code-validator>=0.1.3 -mkdocs-simple-hooks>=0.1.3 diff --git a/requirements.txt b/requirements.txt index 375fcce20..a8a97b026 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,14 +1,14 @@ # -# This file is autogenerated by pip-compile with Python 3.11 +# This file is autogenerated by pip-compile with Python 3.12 # by the following command: # # pip-compile requirements.in # -babel==2.12.1 +babel==2.14.0 # via mkdocs-material -certifi==2023.7.22 +certifi==2024.2.2 # via requests -charset-normalizer==3.2.0 +charset-normalizer==3.3.2 # via requests click==8.1.7 # via mkdocs @@ -16,28 +16,30 @@ colorama==0.4.6 # via mkdocs-material ghp-import==2.1.0 # via mkdocs -idna==3.4 +idna==3.7 # via requests -jinja2==3.1.2 +jinja2==3.1.3 # via # mkdocs # mkdocs-material -markdown==3.4.4 +markdown==3.6 # via # markdown-callouts # mkdocs # mkdocs-code-validator # mkdocs-material # pymdown-extensions -markdown-callouts==0.3.0 +markdown-callouts==0.4.0 # via -r requirements.in -markupsafe==2.1.3 +markupsafe==2.1.5 # via # jinja2 # mkdocs mergedeep==1.3.4 - # via mkdocs -mkdocs==1.5.2 + # via + # mkdocs + # mkdocs-get-deps +mkdocs==1.6.0 # via # -r requirements.in # mkdocs-code-validator @@ -45,51 +47,51 @@ mkdocs==1.5.2 # mkdocs-material # mkdocs-redirects # mkdocs-section-index - # mkdocs-simple-hooks mkdocs-code-validator==0.2.0 # via -r requirements.in +mkdocs-get-deps==0.2.0 + # via mkdocs mkdocs-literate-nav==0.6.1 # via -r requirements.in -mkdocs-material==9.3.1 +mkdocs-material==9.5.2 # via -r requirements.in -mkdocs-material-extensions==1.1.1 +mkdocs-material-extensions==1.3.1 # via mkdocs-material mkdocs-redirects==1.2.1 # via -r requirements.in -mkdocs-section-index==0.3.7 - # via -r requirements.in -mkdocs-simple-hooks==0.1.5 +mkdocs-section-index==0.3.9 # via -r requirements.in -packaging==23.1 +packaging==24.0 # via mkdocs paginate==0.5.6 # via mkdocs-material -pathspec==0.11.2 - # via mkdocs -platformdirs==3.10.0 +pathspec==0.12.1 # via mkdocs -pygments==2.16.1 +platformdirs==4.2.0 + # via mkdocs-get-deps +pygments==2.17.2 # via mkdocs-material -pymdown-extensions==10.3 +pymdown-extensions==10.8 # via # mkdocs-code-validator # mkdocs-material -python-dateutil==2.8.2 +python-dateutil==2.9.0.post0 # via ghp-import pyyaml==6.0.1 # via # mkdocs + # mkdocs-get-deps # pymdown-extensions # pyyaml-env-tag pyyaml-env-tag==0.1 # via mkdocs -regex==2023.8.8 +regex==2024.4.16 # via mkdocs-material requests==2.31.0 # via mkdocs-material six==1.16.0 # via python-dateutil -urllib3==2.0.4 +urllib3==2.2.1 # via requests -watchdog==3.0.0 +watchdog==4.0.0 # via mkdocs From ed2b37efb2ba074af8b2153b5d5a5724b163df26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Wed, 8 May 2024 19:31:09 +0200 Subject: [PATCH 4/4] Add page *Release Policy* (#756) Co-authored-by: Beta Ziliani --- docs/README.md | 5 ++-- docs/SUMMARY.md | 3 ++- docs/project/release-policy.md | 43 ++++++++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 docs/project/release-policy.md diff --git a/docs/README.md b/docs/README.md index 117b7e012..8cbcf8f13 100644 --- a/docs/README.md +++ b/docs/README.md @@ -114,11 +114,12 @@ Instructions on how to use the compiler and tools.
-### Developer News +### Project and Releases Information Announcements about the language development. -* [Release Notes](https://crystal-lang.org/blog/#release_notes) +* [Release Notes](https://crystal-lang.org/releases) +* [Release Policy](project/release-policy.md) * [Crystal Blog](https://crystal-lang.org/blog)
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 485b5ae68..e7d63f33d 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -103,7 +103,6 @@ * [asm](syntax_and_semantics/asm.md) * [Compile-time flags](syntax_and_semantics/compile_time_flags.md) * [Cross-compilation](syntax_and_semantics/cross-compilation.md) - * [Platform Support](syntax_and_semantics/platform_support.md) * [C bindings](syntax_and_semantics/c_bindings/README.md) * [lib](syntax_and_semantics/c_bindings/lib.md) * [fun](syntax_and_semantics/c_bindings/fun.md) @@ -151,3 +150,5 @@ * [Using the Compiler](man/crystal/README.md) * [The Shards Command](man/shards/README.md) * [Required libraries](man/required_libraries.md) + * [Platform Support](syntax_and_semantics/platform_support.md) + * [Release Policy](project/release-policy.md) diff --git a/docs/project/release-policy.md b/docs/project/release-policy.md new file mode 100644 index 000000000..666d12c22 --- /dev/null +++ b/docs/project/release-policy.md @@ -0,0 +1,43 @@ +# Release Policy + +Crystal releases have a version indicated by a major, minor and patch number. + +The current major branch number is `1`. + +New features are added in minor releases (`1.x.0`) which are regularly scheduled every three months. + +Patch releases contain only important bug fixes and are released when necessary. +They usually only appear for the latest minor branch. + +New releases are announced at [crystal-lang.org/releases](https://crystal-lang.org/releases) ([RSS feed](https://crystal-lang.org/releases)). + +There are currently no plans for a new major release. + +## Backwards compatibility + +Minor and patch releases are backwards compatible: Well-defined behaviours and documented APIs in a given version +will continue working on future versions within the same major branch. + +As a result, migrating to a new minor release is usually seamless. + +### Reservations + +Although we expect the vast majority of programs to remain compatible over time, +it is impossible to guarantee that no future change will break any program. +Under some unlikely circumstances, we may introduce changes that break existing code. +Rest assured we are commited to keep the impact as minimal as possible. + +* Security: a security issue in the implementation may arise whose resolution requires backwards incompatible changes. We reserve the right to address such security issues. + +* Bugs: if an API has undesired behaviour, a program that depends on the buggy behaviour may break if the bug is fixed. We reserve the right to fix such bugs. + +* Compiler front-end: improvements may be done to the compiler, introducing new warnings for ambiguous modes and providing more detailed error messages. Those can lead to compilation errors (when building with `--error-on-warnings`) or tooling failures when asserting on specific error messages (although one should avoid such). We reserve the right to do such improvements. + +* Feature additions: When introducing new features into the language or core library, there can be collisions with the names of types, methods, etc. defined in user code. We reserve the right to add new names when necessary. + +The changelog and release notes highlight any changes that have a considerable potential for breaking existing code, even if it uses experimental, undocumented or unsupported features. + +### Experimental features + +The only exception to the compatibility guarantees are experimental features, which are explicitly designated as such with the [`@[Experimental]`](https://crystal-lang.org/api/Experimental.html) annotation. +There is no compatibility guarantee until they are stabilized (at which point the annotation is dropped).