The Miji is designed to help Python users quickly adapt to Mojo, highlighting the similarities and differences between the two languages. It tries to provide additional insights, tips, conceptual models that do not present in the official documentation but would be helpful for understanding Mojo from a Pythonista’s perspective, e.g., quaternary system of variable, four statuses of ownership, diagrams of memory layouts for some data structures and operations, etc. Readers can use this Miji as a complementary resource to the official Mojo manual.
The term “Miji” is derived from the Chinese word “秘籍”, which means “secret book” or “manual”. It is often used to refer to a guide or handbook that provides valuable insights, tips, and shortcuts for mastering a particular subject.
The first four parts of the Miji are summarized as follows.
START: The first part introduces how to set up the Mojo environment on your computer so that you can write your first Mojo program.
MOVE: The second part first shows you how to convert Python code into Mojo code with three examples. Then it highlights the similarities and differences between the two languages. If you are familiar with Python, after reading this part, you will be able to write Mojo code with a certain level of confidence.
BASIC: The third part covers the basic features of Mojo, starting with a conceptual model of variables, and then introducing functions, data types, operators, structs, etc. These features are also present in Python, but Mojo has some differences that you should be aware of. This part will help you to understand the basic syntax and semantics of Mojo.
ADVANCED: The fourth part introduces some more advanced features of Mojo, such as SIMD, parameterization, generic, ownership, etc. These features are not present in Python, but they are essential for writing efficient and safe Mojo code.
MISCELLANEOUS: The final part covers miscellaneous topics, which may be further integrated into the previous parts in the future. This part also includes a glossary of key terms and concepts related to Mojo, as well as a list of information, tips, and warnings that are scattered throughout the Miji. It is particularly helpful if you are already a Magician but want to avoid common pitfalls and mistakes that I encountered while using Mojo.
Although I am continuing working Part V, a case study that implements a matrix struct with Mojo, I still think that it might be a suitable time now to share this Miji in the community, so that more people, particularly Pythonistas, can join in the Mojo world and make Mojo better and popular.
Since Mojo is still evolving, a lot of things in the Miji will be outdated soon. But I will keep it up to date with the latest Mojo version. I will also add more chapters when more functionalities become stable.
Special thanks to you in advance for your feedback!
This is really amazing, great work. The upcoming 25.4 release will close a lot of gaps and improve usability in general in Mojo. Please check out the nightlies changelog if you’re interested.
I only have one small nitpick, which is that we’re trying to get people to use the benchmark module instead of manually timing, since on most systems only timing one operation or one group of operations leaves it vulnerable to the OS scheduler throwing off averages unless you do a very long run. The benchmark module handles that more carefully, while also giving more statistics. Would you be willing to replace the areas you’ve used time.perf_counter_ns() with benchmark.run?
Other than that, this looks like it might be a good version of Rust’s “Rust Book”, but for Mojo.
Thank you for your comments and the information on this benchmark module! I will replace the time.perf_counter_ns() with this benchmark.run() in the code on Data type - SIMD. I am curious whether the statistics are different when I use this benchmark.run().
For the comparison between Mojo, C, Rust, and Python on Example Fibonacci sequence, I think manual clocking would be better because I want to keep the code clean so that it is more comparable between languages. After all, it is a very long run (more than 30 seconds).
Thank you! It is a good question. I wrote this chapter when I was using the 25.4-nightly. I noticed that the ref keyword was not colored if I used ref b = a, so I thought that var ref b = a was a better and more complete syntax to create a reference.
According to the official documentation, the recommended syntax is ref b = a. So I am considering updating this chapter.
Nevertheless, the code var ref b = a also works without error. I am not sure whether this is also a correct way (or the complete syntax) to create a reference (similar to let mut a in Rust). I will keep an eye on this.
@christoph_schlumpf , I found that Chris wrote something in the Discord last year September that:
This will also allow defining local references in a nice enough way: var (ref x) = someArray[idx] and depending on how that stacks out, it would be sensible to allow one to just write ref x = someArray[idx]