From 61a97c6f995ed8a471d9613b908f8f5302283ac4 Mon Sep 17 00:00:00 2001 From: Ken Jones <165197230+KenJones-Modular@users.noreply.github.com> Date: Fri, 13 Sep 2024 09:06:05 -0700 Subject: [PATCH] Update v24.5 release date. Incorporated feedback. Added an introduction to the Highlights section. Fixed various typos and formatting issues. MODULAR_ORIG_COMMIT_REV_ID: 04f5c88e787ed477321f8e337b554d9d6c4b4ca1 --- docs/changelog-released.md | 185 ++++++++++++++++++++----------------- 1 file changed, 102 insertions(+), 83 deletions(-) diff --git a/docs/changelog-released.md b/docs/changelog-released.md index 811a2d885b..4b6d831607 100644 --- a/docs/changelog-released.md +++ b/docs/changelog-released.md @@ -7,8 +7,9 @@ toc_max_heading_level: 2 This is a list of changes to the Mojo language, standard library, and tools. -To check your current version, run `mojo --version`, and then [update Mojo with -`magic`](/magic#update-max-and-mojo). +To check your current version, run `mojo --version`. To update the version of +Mojo for your project with the `magic` package manager, follow the instructions +in [Update a package](/magic#update-a-package) to update the `max` package. :::caution Switch to Magic @@ -19,10 +20,13 @@ conda](/magic/conda). ::: -## v24.5 (2024-09-10) +## v24.5 (2024-09-13) ### ✨ Highlights +Here's a brief summary of some of the major changes in this release, with more +detailed information in the following sections: + - Mojo now supports Python 3.12 interoperability. - The set of automatically imported entities (types, aliases, functions) into @@ -30,33 +34,34 @@ conda](/magic/conda). user code as users will need to explicitly import what they're using for cases previously automatically included before. +- [`print()`](/mojo/stdlib/builtin/io/print) now requires that its arguments + conform to the [`Formattable`](/mojo/stdlib/utils/format/Formattable) trait. + This enables efficient stream-based writing by default, avoiding unnecessary + intermediate String heap allocations. + +- The new builtin [`input()`](/mojo/stdlib/builtin/io/input) function prints an + optional prompt and reads a line from standard input, in the same way as + Python. + - Mojo now allows implicit definitions of variables within a `fn` in the same way that has been allowed in a `def`. The `var` keyword is still allowed, but is now optional. -- Mojo now supports "conditional conformances" where some methods on a struct - have additional trait requirements that the struct itself doesn't. - - Mojo now diagnoses "argument exclusivity" violations due to aliasing references. Mojo requires references (including implicit references due to `borrowed`/`inout` arguments) to be uniquely referenced (non-aliased) if mutable. This is a warning in the 24.5 release, but will be upgraded to an error in subsequent releases. +- Mojo now supports "conditional conformances" where some methods on a struct + have additional trait requirements that the struct itself doesn't. + - `DTypePointer`, `LegacyPointer`, and `Pointer` have been removed. Use [`UnsafePointer`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer) instead. Functions that previously took a `DTypePointer` now take an equivalent `UnsafePointer`. For more information on using pointers, see [Unsafe pointers](/mojo/manual/pointers) in the Mojo Manual. -- [`print()`](/mojo/stdlib/builtin/io/print) now requires that its arguments - conform to the `Formattable` trait. This enables efficient stream-based - writing by default, avoiding unnecessary intermediate String heap allocations. - -- The new builtin [`input()`](/mojo/stdlib/builtin/io/input) function prints an - optional prompt and reads a line from standard input, in the same way as - Python. - - There are many new standard library APIs, with new features for strings, collections, and interacting with the filesystem and environment. Changes are listed in the standard library section. @@ -72,7 +77,11 @@ conda](/magic/conda). ### Language changes -#### ⭐️ New +- Mojo now allows implicit definitions of variables within a `fn` in the same + way that has been allowed in a `def`. The `var` keyword is still allowed and + still denotes the declaration of a new variable with a scope (in both `def` + and `fn`). Relaxing this makes `fn` and `def` more similar, but they still + differ in other important ways. - Mojo now diagnoses "argument exclusivity" violations due to aliasing references. Mojo requires references (including implicit references due to @@ -103,11 +112,59 @@ conda](/magic/conda). implementation details are somewhat different because lifetimes are embedded in types. -- Mojo now allows implicit definitions of variables within a `fn` in the same - way that has been allowed in a `def`. The `var` keyword is still allowed and - still denotes the declaration of a new variable with a scope (in both `def` - and `fn`). Relaxing this makes `fn` and `def` more similar, but they still - differ in other important ways. + This is a warning in the 24.5 release, but will be upgraded to an error in + subsequent releases. + + :::note + + Argument exclusivity is not enforced for register-passable types. They are + passed by copy, so they don't form aliases. + + ::: + +- Mojo now supports "conditional conformances" where some methods on a struct + have additional trait requirements that the struct itself doesn't. This is + expressed through an explicitly declared `self` type: + + ```mojo + struct GenericThing[Type: AnyType]: # Works with anything + # Sugar for 'fn normal_method[Type: AnyType](self: GenericThing[Type]):' + fn normal_method(self): ... + + # Just redeclare the requirements with more specific types: + fn needs_move[Type: Movable](self: GenericThing[Type], owned val: Type): + var tmp = val^ # Ok to move 'val' since it is Movable + ... + fn usage_example(): + var a = GenericThing[Int]() + a.normal_method() # Ok, Int conforms to AnyType + a.needs_move(42) # Ok, Int is movable + + var b = GenericThing[NonMovable]() + b.normal_method() # Ok, NonMovable conforms to AnyType + + # error: argument type 'NonMovable' does not conform to trait 'Movable' + b.needs_move(NonMovable()) + ``` + + Conditional conformance works with dunder methods and other things as well. + +- As a specific form of "conditional conformances", initializers in a struct + may indicate specific parameter bindings to use in the type of their `self` + argument. For example: + + ```mojo + @value + struct MyStruct[size: Int]: + fn __init__(inout self: MyStruct[0]): pass + fn __init__(inout self: MyStruct[1], a: Int): pass + fn __init__(inout self: MyStruct[2], a: Int, b: Int): pass + + def test(x: Int): + a = MyStruct() # Infers size=0 from 'self' type. + b = MyStruct(x) # Infers size=1 from 'self' type. + c = MyStruct(x, x) # Infers size=2 from 'self' type. + ``` - Mojo now supports named result bindings. Named result bindings are useful for directly emplacing function results into the output slot of a function. This @@ -172,50 +229,6 @@ conda](/magic/conda). print(x) # no longer complains about 'x' being uninitialized ``` -- Mojo now supports "conditional conformances" where some methods on a struct - have additional trait requirements that the struct itself doesn't. This is - expressed through an explicitly declared `self` type: - - ```mojo - struct GenericThing[Type: AnyType]: # Works with anything - # Sugar for 'fn normal_method[Type: AnyType](self: GenericThing[Type]):' - fn normal_method(self): ... - - # Just redeclare the requirements with more specific types: - fn needs_move[Type: Movable](self: GenericThing[Type], owned val: Type): - var tmp = val^ # Ok to move 'val' since it is Movable - ... - fn usage_example(): - var a = GenericThing[Int]() - a.normal_method() # Ok, Int conforms to AnyType - a.needs_move(42) # Ok, Int is movable - - var b = GenericThing[NonMovable]() - b.normal_method() # Ok, NonMovable conforms to AnyType - - # error: argument type 'NonMovable' does not conform to trait 'Movable' - b.needs_move(NonMovable()) - ``` - - Conditional conformance works with dunder methods and other things as well. - -- As a specific form of "conditional conformances", initializers in a struct - may indicate specific parameter bindings to use in the type of their `self` - argument. For example: - - ```mojo - @value - struct MyStruct[size: Int]: - fn __init__(inout self: MyStruct[0]): pass - fn __init__(inout self: MyStruct[1], a: Int): pass - fn __init__(inout self: MyStruct[2], a: Int, b: Int): pass - - def test(x: Int): - a = MyStruct() # Infers size=0 from 'self' type. - b = MyStruct(x) # Infers size=1 from 'self' type. - c = MyStruct(x, x) # Infers size=2 from 'self' type. - ``` - - `async` functions now support memory-only results (like `String`, `List`, etc.) and `raises`. Accordingly, both [`Coroutine`](/mojo/stdlib/builtin/coroutine/Coroutine) and @@ -251,11 +264,9 @@ conda](/magic/conda). export MOJO_PYTHON="~/venv/bin/python" ``` - `MOJO_PYTHON_LIBRARY` still exists for environments with a dynamic libpython, + `MOJO_PYTHON_LIBRARY` still exists for environments with a dynamic `libpython` but no Python executable. -#### 🦋 Changed - - The pointer aliasing semantics of Mojo have changed. Initially, Mojo adopted a C-like set of semantics around pointer aliasing and derivation. However, the C semantics bring a lot of history and baggage that are not needed in Mojo and @@ -323,12 +334,12 @@ conda](/magic/conda). print("Hello, " + name + "!") ``` - If the user enters "Mojo" it returns "Hello Mojo!" + If the user enters "Mojo" it returns "Hello, Mojo!" - [`print()`](/mojo/stdlib/builtin/io/print) now requires that its arguments - conform to the `Formattable` trait. This enables efficient stream-based - writing by default, avoiding unnecessary intermediate String heap - allocations. + conform to the [`Formattable`](/mojo/stdlib/utils/format/Formattable) trait. + This enables efficient stream-based writing by default, avoiding unnecessary + intermediate String heap allocations. Previously, `print()` required types conform to [`Stringable`](/mojo/stdlib/builtin/str/Stringable). This meant that to @@ -374,7 +385,7 @@ conda](/magic/conda). - :::note TODO + :::note The error shown when passing a type that does not implement `Formattable` to `print()` is currently not entirely descriptive of the underlying cause: @@ -462,11 +473,17 @@ conda](/magic/conda). method to `String` and `StringLiteral`, which returns an `UnsafePointer[C_char]` for convenient interoperability with C APIs. - - Added the `byte_length()` method to `String`, `StringSlice`, and - `StringLiteral` and deprecated their private `_byte_length()` methods. - Added a warning to `String.__len__` method that it will return length in - Unicode codepoints in the future and `StringSlice.__len__()` now does return - the Unicode codepoints length. + - Added the `byte_length()` method to + [`String`](/mojo/stdlib/collections/string/String#byte_length), + [`StringSlice`](/mojo/stdlib/utils/string_slice/StringSlice#byte_length), + and + [`StringLiteral`](/mojo/stdlib/builtin/string_literal/StringLiteral#byte_length) + and deprecated their private `_byte_length()` methods. Added a warning to + the [`String.__len__()`](/mojo/stdlib/collections/string/String#__len__) + method that it will return the length in Unicode codepoints in the future + and + [`StringSlice.__len__()`](/mojo/stdlib/utils/string_slice/StringSlice#__len__) + now does return the Unicode codepoints length. ([PR #2960](https://github.com/modularml/mojo/pull/2960)) - Added a new [`StaticString`](/mojo/stdlib/utils/string_slice/#aliases) type @@ -482,7 +499,8 @@ conda](/magic/conda). `DTypePointer.int8` have been changed to take a `UnsafePointer[C_char]`, reflecting their use for compatibility with C APIs. - - Continued transition to `UnsafePointer` and unsigned byte type for strings: + - Continued the transition to `UnsafePointer` and unsigned byte type for + strings: - [`String.unsafe_ptr()`](/mojo/stdlib/collections/string/String#unsafe_ptr) now returns an `UnsafePointer[UInt8]` (was `UnsafePointer[Int8]`) @@ -548,8 +566,9 @@ conda](/magic/conda). - `initialize_pointee_copy(p, value)` => [`p.init_pointee_copy(value)`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer#init_pointee_copy) - `move_pointee(src=p1, dst=p2)` => [`p.move_pointee_into(p2)`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer#move_pointee_into) - - The `UnsafePointer.offset()` method has been removed. Use - [pointer arithmetic](/mojo/manual/pointers#storing-multiple-values) instead. + - The `UnsafePointer.offset()` method is deprecated and will be removed in a + future release. Use [pointer + arithmetic](/mojo/manual/pointers#storing-multiple-values) instead. ```mojo new_ptr = ptr.offset(1) @@ -667,12 +686,12 @@ conda](/magic/conda). - Filesystem and environment utilities: - [`Path.home()`](/mojo/stdlib/pathlib/path/Path#home) has been added to - return a path of the users home directory. + return a path of the user's home directory. - [`os.path.expanduser()`](/mojo/stdlib/os/path/path/expanduser) and [`pathlib.Path.exapanduser()`](/mojo/stdlib/pathlib/path/Path#expanduser) have been added to allow expanding a prefixed `~` in a `String` or `Path` - with the users home path: + with the user's home path: ```mojo import os @@ -756,7 +775,7 @@ conda](/magic/conda). - [`NoneType`](/mojo/stdlib/builtin/none/NoneType) is now a normal standard library type, and not an alias for a raw MLIR type. - Function signatures spelled as `fn() -> NoneType` should transition to + Function signatures written as `fn() -> NoneType` should transition to being written as `fn() -> None`. - Mojo now has a [`UInt`](/mojo/stdlib/builtin/uint/UInt) type for modeling