AdaCore · frank-at-adacore · Jan 31, 2025 · Feb 3, 2025 · Feb 4, 2025 · Feb 4, 2025
diff --git a/contrib/rst_files_with_prelude.txt b/contrib/rst_files_with_prelude.txt
@@ -10,3 +10,4 @@ courses/gnattest/*.rst
 courses/gnat_project_facility/*.rst
 courses/gnatcoverage/*.rst
 courses/rust_essentials/*.rst
+courses/comprehensive_rust_training/*.rst
diff --git a/courses/advanced_exception_analysis/010_advanced_exception_analysis.rst b/courses/advanced_exception_analysis/010_advanced_exception_analysis.rst
@@ -15,6 +15,9 @@ Advanced Exception Analysis
 .. role:: cpp(code)
     :language: C++
 
+.. role:: rust(code)
+    :language: Rust
+
 .. container:: PRELUDE SYMBOLS
 
 .. |rightarrow| replace:: :math:`\rightarrow`

diff --git a/courses/comprehensive_rust_training/010_introduction.rst b/courses/comprehensive_rust_training/010_introduction.rst
@@ -0,0 +1,44 @@
+************
+Introduction
+************
+
+.. container:: PRELUDE BEGIN
+
+.. container:: PRELUDE ROLES
+
+.. role:: ada(code)
+    :language: Ada
+
+.. role:: C(code)
+    :language: C
+
+.. role:: cpp(code)
+    :language: C++
+
+.. role:: rust(code)
+    :language: Rust
+
+.. container:: PRELUDE SYMBOLS
+
+.. |rightarrow| replace:: :math:`\rightarrow`
+.. |forall| replace:: :math:`\forall`
+.. |exists| replace:: :math:`\exists`
+.. |equivalent| replace:: :math:`\iff`
+.. |le| replace:: :math:`\le`
+.. |ge| replace:: :math:`\ge`
+.. |lt| replace:: :math:`<`
+.. |gt| replace:: :math:`>`
+.. |checkmark| replace:: :math:`\checkmark`
+
+.. container:: PRELUDE REQUIRES
+
+.. container:: PRELUDE PROVIDES
+
+..
+   About Adacore
+   About This Training
+
+.. container:: PRELUDE END
+
+.. include:: 010_introduction/01-about_adacore.rst
+.. include:: 010_introduction/02-about_this_training.rst
diff --git a/courses/comprehensive_rust_training/010_introduction/01-about_adacore.rst b/courses/comprehensive_rust_training/010_introduction/01-about_adacore.rst
@@ -0,0 +1,21 @@
+=============
+About AdaCore
+=============
+
+-----------
+The Company
+-----------
+
+..
+    Taken from https://www.adacore.com/company/about
+
+* Founded in 1994
+* Centered around helping developers build **safe, secure and reliable** software
+* Headquartered in New York and Paris
+
+   - Representatives in countries around the globe
+
+* Roots in Open Source software movement
+
+    - GNAT compiler is part of GNU Compiler Collection (GCC)
+
diff --git a/courses/comprehensive_rust_training/010_introduction/02-about_this_training.rst b/courses/comprehensive_rust_training/010_introduction/02-about_this_training.rst
@@ -0,0 +1,83 @@
+===================
+About This Training
+===================
+
+--------------------------
+Your Trainer
+--------------------------
+
+* Experience in software development
+
+    - Languages
+    - Methodology
+
+* Experience teaching this class
+
+-----------------------------
+Goals of the training session
+-----------------------------
+
+* What you should know by the end of the training
+* Syllabus overview
+
+    - The syllabus is a guide, but we might stray off of it
+    - ...and that's OK: we're here to cover **your needs**
+
+----------
+Roundtable
+----------
+
+* 5 minute exercise
+
+    - Write down your answers to the following
+    - Then share it with the room
+
+* Experience in software development
+
+    - Languages
+    - Methodology
+
+* Experience and interest with the syllabus
+
+    - Current and upcoming projects
+    - Curious for something?
+
+* Your personal goals for this training
+
+    - What do you want to have coming out of this?
+
+* Anecdotes, stories... feel free to share!
+
+    - Most interesting or funny bug you've encountered?
+    - Your own programming interests?
+
+-------------------
+Course Presentation
+-------------------
+
+* Slides
+* Quizzes
+* Labs
+
+    - Hands-on practice
+    - Recommended setup: latest GNAT Studio
+    - Class reflection after some labs
+
+* Demos
+
+    - Depending on the context
+
+* Daily schedule
+
+--------
+Styles
+--------
+
+* :dfn:`This` is a definition
+* :filename:`this/is/a.path`
+* :ada:`code is highlighted`
+* :command:`commands are emphasised --like-this`
+
+.. warning:: This is a warning
+.. note:: This is an important piece of info
+.. tip:: This is a tip
diff --git a/courses/comprehensive_rust_training/020_hello_world.rst b/courses/comprehensive_rust_training/020_hello_world.rst
@@ -0,0 +1,41 @@
+*************
+Hello World
+*************
+
+.. container:: PRELUDE BEGIN
+
+.. container:: PRELUDE ROLES
+
+.. role:: ada(code)
+    :language: Ada
+
+.. role:: C(code)
+    :language: C
+
+.. role:: cpp(code)
+    :language: C++
+
+.. role:: rust(code)
+    :language: Rust
+
+.. container:: PRELUDE SYMBOLS
+
+.. |rightarrow| replace:: :math:`\rightarrow`
+.. |forall| replace:: :math:`\forall`
+.. |exists| replace:: :math:`\exists`
+.. |equivalent| replace:: :math:`\iff`
+.. |le| replace:: :math:`\le`
+.. |ge| replace:: :math:`\ge`
+.. |lt| replace:: :math:`<`
+.. |gt| replace:: :math:`>`
+.. |checkmark| replace:: :math:`\checkmark`
+
+.. container:: PRELUDE REQUIRES
+
+.. container:: PRELUDE PROVIDES
+
+.. container:: PRELUDE END
+
+.. include:: 020_hello_world/01_what_is_rust.rst
+.. include:: 020_hello_world/02_benefits.rst
+.. include:: 020_hello_world/03_playground.rst
diff --git a/courses/comprehensive_rust_training/020_hello_world/01_what_is_rust.rst b/courses/comprehensive_rust_training/020_hello_world/01_what_is_rust.rst
@@ -0,0 +1,46 @@
+===============
+What is Rust?
+===============
+
+---------------
+What is Rust?
+---------------
+
+Rust is a new programming language which had its `1.0 release in
+2015 <https://blog.rust-lang.org/2015/05/15/Rust-1.0.html>`__:
+
+-  Rust is a statically compiled language in a similar role as C++
+
+   -  :command:`rustc` uses LLVM as its backend.
+
+-  Rust supports many `platforms and
+   architectures <https://doc.rust-lang.org/nightly/rustc/platform-support.html>`__:
+
+   -  x86, ARM, WebAssembly, ...
+   -  Linux, Mac, Windows, ...
+
+-  Rust is used for a wide range of devices:
+
+   -  firmware and boot loaders,
+   -  smart displays,
+   -  mobile phones,
+   -  desktops,
+   -  servers.
+
+.. raw:: html
+
+---------
+Details
+---------
+
+Rust fits in the same area as C++:
+
+-  High flexibility.
+-  High level of control.
+-  Can be scaled down to very constrained devices such as
+   microcontrollers.
+-  Has no runtime or garbage collection.
+-  Focuses on reliability and safety without sacrificing performance.
+
+.. raw:: html
+
diff --git a/courses/comprehensive_rust_training/020_hello_world/02_benefits.rst b/courses/comprehensive_rust_training/020_hello_world/02_benefits.rst
@@ -0,0 +1,65 @@
+==================
+Benefits of Rust
+==================
+
+------------------
+Benefits of Rust
+------------------
+
+Some unique selling points of Rust:
+
+-  *Compile time memory safety* - whole classes of memory bugs are
+   prevented at compile time
+
+   -  No uninitialized variables.
+   -  No double-frees.
+   -  No use-after-free.
+   -  No null pointers.
+   -  No forgotten locked mutexes.
+   -  No data races between threads.
+   -  No iterator invalidation.
+
+-  *No undefined runtime behavior* - what a Rust statement does is never
+   left unspecified
+
+   -  Array access is bounds checked.
+   -  Integer overflow is defined (panic or wrap-around).
+
+-  *Modern language features* - as expressive and ergonomic as
+   higher-level languages
+
+   -  Enums and pattern matching.
+   -  Generics.
+   -  No overhead FFI.
+   -  Zero-cost abstractions.
+   -  Great compiler errors.
+   -  Built-in dependency manager.
+   -  Built-in support for testing.
+   -  Excellent Language Server Protocol support.
+
+.. raw:: html
+
+---------
+Details
+---------
+
+Do not spend much time here. All of these points will be covered in more
+depth later.
+
+Make sure to ask the class which languages they have experience with.
+Depending on the answer you can highlight different features of Rust:
+
+-  Experience with C or C++: Rust eliminates a whole class of *runtime
+   errors* via the borrow checker. You get performance like in C and
+   C++, but you don't have the memory unsafety issues. In addition, you
+   get a modern language with constructs like pattern matching and
+   built-in dependency management.
+
+-  Experience with Java, Go, Python, JavaScript...: You get the same
+   memory safety as in those languages, plus a similar high-level
+   language feeling. In addition you get fast and predictable
+   performance like C and C++ (no garbage collector) as well as access
+   to low-level hardware (should you need it).
+
+.. raw:: html
+
diff --git a/courses/comprehensive_rust_training/020_hello_world/03_playground.rst b/courses/comprehensive_rust_training/020_hello_world/03_playground.rst
@@ -0,0 +1,37 @@
+============
+Playground
+============
+
+------------
+Playground
+------------
+
+The `Rust Playground <https://play.rust-lang.org/>`__ provides an easy
+way to run short Rust programs, and is the basis for the examples and
+exercises in this course. Try running the "hello-world" program it
+starts with. It comes with a few handy features:
+
+-  Under "Tools", use the :menu:`rustfmt` option to format your code in the
+   "standard" way.
+
+-  Rust has two main "profiles" for generating code: Debug (extra
+   runtime checks, less optimization) and Release (fewer runtime checks,
+   lots of optimization). These are accessible under "Debug" at the top.
+
+-  If you're interested, use :menu:`ASM` under :menu:`...` to see the generated
+   assembly code.
+
+.. raw:: html
+
+---------
+Details
+---------
+
+As students head into the break, encourage them to open up the
+playground and experiment a little. Encourage them to keep the tab open
+and try things out during the rest of the course. This is particularly
+helpful for advanced students who want to know more about Rust's
+optimizations or generated assembly.
+
+.. raw:: html
+