Lab 0: Rustlings ================ - **Handed out:** Tuesday, January 7, 2020 - **Due:** Monday, January 20, 2020 Introduction ------------ Welcome to CS3210! We're really excited that you've decided to join us for this inaugural incarnation. We hope you have as much fun taking this class as we've had developing it! And, of course, we hope you learn a ton. We're hoping to do things a little differently in CS3210 than the norm. In particular, we want *you* to write the majority of the code, and we want your code to execute on *real* hardware, doing *real* things. There's going to be very little scaffolding provided for you, and all of your code will target and run on the Raspberry Pi 3/B/B+, a quad-core ARMv8 Cortex-A53 based embedded platform. Unlike last serveral years, we'll be programming a toy OS in `Rust `__, "a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety." You can think of Rust as a successor to C and C++, but it's more useful to think of it as a brand new language with new concepts. Don't try to program in Rust as if it's C, C++, Java, or any other language you're used to. Instead, see it as an opportunity to learn a new way to write software - a new *rusty* way. By the end of the term, we think you'll agree that Rust helps you write more correct, more reliable, and importantly more secure software, which are the key properties for operating systems! You'll be writing a lot of code in CS3210, though we think that the majority of your time will be spent thinking about what needs to happen. We expect that most assignments will take about 15-20 hours a week to complete, which means you should, under no circumstance, procrastinate in CS3210. Start early, ask questions, visit us at the office hours, and importantly have fun - you'll learn much more if you give yourself a chance to think through hard problems. We're here to answer any and all questions. Please don't hesitate to reach out to us. Best of luck! Overview ~~~~~~~~ Mastering a programming language takes time. In fact, truly mastering a single programming language takes *long* time, perhaps our lifetime. In other words, it's unrealistic to assume that we become a true master of Rust in a week - but we all hope we can start tinkering anything with Rust at the end of this semester. As a warm up, we will spend sometime to understand syntactic as well as semantic foundation of the Rust programming language by answering a series of questions we prepared. To get set up your environment, let's first install required dependencies and the Rust ecosystems, namely ``rustc`` and ``cargo``. We assume that you are doing the assignments on a latest LTS Ubuntu distribution (i.e., Ubuntu 18.04 LTS). If you are not running Ubuntu natively, please check the `Tool `__ page to prepare a Ubuntu virtual machine. Also if you are not familiar with ``git``, please first check `Pro Git Book `__. .. code-block:: sh $ git clone https://github.com/sslab-gatech/cs3210-rustos-public.git --origin skeleton rustos $ cd rustos # This script automatically setup the environment $ bin/setup.sh ... $ export PATH=$HOME/.cargo/bin:$PATH $ rustc --version rustc 1.37.0-nightly (0af8e872e 2019-06-30) In the repository, we try hard to keep everything in place - no additional download or dependencies. It looks like: .. code-block:: none . ├── bin : common binaries/utilities (e.g., objdump for aarch64) ├── doc : reference documents └── tut : tutorial/practices (i.e., no further reuse for later labs) └── 0-rustlings : this contains files for lab0 Rustlings --------- .. figure:: https://i.imgur.com/LbZJgmm.gif :align: center :width: 300px Our goal of lab0 is to guide you to read from `Chapter 1 `__ to `Chapter 18 `__ of `Rust By Example `__. To check your understanding, we will use `Rustlings `__, which is a neat way to get familiarized with Rust by solving a series of *simple* exercises. It provides an interactive session of training by comprehending the compiler error messages and resolving it. While doing exercises, you would like to read various chapters of `The Rust Book `__. You can also find more pointers on Rust in the course's reference page. .. code-block:: sh $ cd tut/0-rustlings $ ./rustlings help ... SUBCOMMANDS: help Prints this message or the help of the given subcommand(s) hint Returns a hint for the current exercise run Runs/Tests a single exercise verify Verifies all exercises according to the recommended order watch Reruns `verify` when files were edited To start your exercise, you can invoke the ``watch`` command that guides you which exercise to work on in a proper order: .. code-block:: sh $ ./rustlings watch If you'd like, you can also do each exercise (files in ``exercises/``) by invoking ``./rustling run [name]``. .. code-block:: sh $ ./rustlings run variables1 ! Compilation of exercises/variables/variables1.rs failed! Compiler error message: error[E0425]: cannot find value `x` in this scope --> exercises/variables/variables1.rs:12:5 | 12 | x = 5; | ^ not found in this scope error[E0425]: cannot find value `x` in this scope --> exercises/variables/variables1.rs:13:36 | 13 | println!("x has the value {}", x); | ^ not found in this scope error: aborting due to 2 previous errors For more information about this error, try `rustc --explain E0425`. If you find the exercise too difficult, ask rustlings for hints of the exercise, like below: .. code-block:: sh $ rustlings hint variables1 Hint: The declaration on line 12 is missing a keyword that is needed in Rust to create a new variable binding To complete this assignment, ``./rusting verify`` should say all the prepared exercises are successfully completed! Assignment Submission --------------------- We are going to use `Georgia Tech's GitHub `__ for the assignment submission in CS3210. After logging into the system, `create a repository `__ named ``rustos``. When creating the repository, **make it private** and **do not initialize the repository with a README**. Next, give TAs' accounts access to your repository for the grading purpose. You should add us in ``Settings > Collaborators`` in your repository menu. * Yechan Bae (ybae38) * Sujin Park (spark800) * Mansour Alharthi (malharthi9) * Taesoo Kim (tkim92) Once you have created the repository, **inform us via** `Google Form `__. To submit your code for lab0, push a commit to the GitHub repository with a tag named ``lab0-done``. We will fetch the assignment code from your repository on each deadline. The following git command samples might be helpful. .. code-block:: sh # connect your local repository to GitHub $ git remote add origin https://github.gatech.edu/[id]/rustos $ git push -u origin master # make a commit and publish the update $ git status $ git add -A $ git commit -a -m "yay, lab0 done!" $ git push # submit lab0 $ git tag lab0-done $ git push --tags Grading Policy ~~~~~~~~~~~~~~ Your score will be simply calculated based on the submission date of the "completed" assignment. The meaning of "completion" is for your repository to be **tagged** as "labN-done" (e.g., lab0-done). If your code in the repo passes all test cases provided as part of the assignment **on time**, you will get the maximum score (i.e., 100) for the corresponding lab. If you are late in submitting the completed assignment, your score of the lab will be ``max(0, 100*[#passes/#testcases] - [#late-day]*10)``, in theory. However, we give **a week** (7 days in total for all labs) of a grace period, which you can use without even letting us know! For example, if you are one-day late in submitting the first lab (i.e., the completed lab0), you still get 100 points for the lab but your grace period is *first* reduced to 6 days. Once you don't have any grace period left, the above rule for the lab effectively takes place. For example, if you don't have any grace period but again late in submitting the lab one day, your score would be ``max(0, 100 - 1*10)``, so ``90`` for the completed lab. We will regularly fetch your repository after the initial deadline, and your score and the grace period will be automatically updated on canvas. Please `send us an email `__ if you made a late change to the assignment and your score had not updated for a week. We really hope *all* the students in this class get A!