# Introduction to the Development Environment

# TODO

Here are the things we need to cover in worksheet/exercises:

1. Rework all the tasks here to be actually be about characterizing code and analyzing traces with Moneta.
2. Look at the formatting for the `README.md` in the FinalProject repo. For mat the questions for this lab in the same way.
3. Add questions for each of the tasks they need to complete.
4. Add the Moneta Tutorial.
5. Make the data structure zoo PART II? Or the yet-to-be-written compiler lab.
6. Or maybe there is no part II

# End TODO

In this lab you will set up the lab environment and learn how gather information about programs using the course tools. You will download some starter code, build and run it in a Docker container, modify the code and push the changes to a git repo. Run the code in the cloud on our reference processor to gather some data.

This lab will be completed on your own. Completing this lab in a timely manner is necessary for passing this course.

Check the course schedule for due date(s).

## FAQ and Updates

Watch here for answers to FAQs and notifications about important updates.

## Integrated Worksheet and README

**READ THIS CAREFULLY**

`README.pdf` is both the lab instructions and your worksheet for the lab. You should use the provided `README.pdf` to fill in your answers for this lab. **You should not generate your own pdf**, since the formatting may not match.

As bugs are found in the lab, we may update `README.md`. We **will not** update `README.pdf` so we can ensure that everyone is using the `README.pdf` to submit answers.

We will maintain a FAQ/important updates section at the top of `README.md` *and* incorporate changes into the body of the document.

## Annotating PDFs

We realize that marking up PDFs is kind of terrible, but it's the best solution we've found to the problem of submitting and grading these labs (we have considered, many, many alternatives and none of them work well for all students). To make it as easy as possible, here are some options.

**Option 1**: Write in the PDF itself using either text-based or freeform (e.g., writing with a tablet) annotation tools.

**Option 2**: Convert the homework PDF to images and use those images as backgrounds in Word or LaTeX or Google Slides (Google Docs doesn’t really support background images). Type on it, then save it as a PDF.

1. You can try exploring the following resources to edit pdfs to fill in your Homework Solutions.

1. https://www.pdfescape.com/open/
2. https://simplypdf.com/
3. https://www.foxitsoftware.com/

## Keeping Your Repo Up-to-Date

Occasionally, there will be changes made to the base repository after the
assignment is released. This may include bug fixes and updates to `README.md`.

In those cases, you can use the following commands to pull the changes from upstream and merge them into your code.

runlab --check-for-updates
runlab --merge-updates

_You'll learn more about `runlab` during this lab._

## Grading

This is a 2 week lab with a checkpoint after one week.

Your grade for this lab will be based on your completion of the data collection steps described in this document and the completed worksheet.

| Part | value |
|----------------------------|-------|
| Part 1 | 23% |
| Part 2 | 23% |
| **FIXME** | 31% |

Part 1 of `README.pdf` is due after the first week. Part 2 and the rest of the lab is due after the second. You can turn them in late for 75% credit. We will only grade one submission for each part.

No late work or extensions will be allowed.

Note that you will submit _the entire_ `README.pdf` (don't remove any pages) for Part 1 and Part 2. For the Part 1 submission, we will only grade Part 1. For the part 2 submission will we will only grade Part 2. etc.

Please check gradescope for exact due dates.

## Skills to Learn

1. Install and use Docker
2. git/GitHub basics
3. Building and modifying lab code
4. Running a job on the autograder

## Academic Integrity Agreement

Open the file `ExcelWithIntegrity.md`, read it, and fill out the form and sign it as directed. The document describes the expectations for this class regarding academic intergrity.

Commit and push the modified file.

## Software You Will Need

1. A computer with Docker installed (either the cloud docker container via ssh, or your own laptop). If you are using you're own machine, you'll need at least 8GB of free memory.
2. The lab for the github classroom assignment for this lab. Find the link on the course home page: https://github.com/CSE141pp/Home/.
3. A PDF annotator/editor to fill out `README.pdf`.

# PART I: A Tour Of the Tools

## Fill Out The Self Evaluation

**FIXME**

Login to your [e-mail]__ gmail account and fill out [this
survey](https://docs.google.com/forms/d/e/1FAIpQLSfLCN85SHaJr5dGAElpZWOPK0sRrbyWqIBcOD4ZW4rxnjjgJA/viewform).
You do not need to do this again if you already filled it out for CSE 142.

## Get set up Github

We are going to use Github classroom for this course. You'll need to [create a Github account](https://github.com/), if you don't already have one. For each part of the project, there will be an assignment setup on Github.

First, you'll need to authorize github classroom to access your github account. To do that, visit https://classroom.github.com and sign in with your github account.

We will be using Github a lot in class. If you aren't familiar with it, there are a bunch of good introductory tutorials. For example, [this one](http://try.github.io/).

## Get Docker Working

All your work for the class will be done in a docker container. Docker containers are self-contained Linux-based workspaces. Using docker ensures that your code runs in a consistent environment for you and the autograder/course staff.

There are two options for getting getting access to docker.

1. Use the campus servers (which is the supported method).
2. Run docker on your own machine (which is not supported, but there there is [some documentation](RunningDocker.md)).

To use the campus servers, you'll also need to be on the [campus VPN](https://blink.ucsd.edu/technology/network/connections/off-campus/VPN/).

### Use dsmlp-login.ucsd.edu

This is the official way to use the class infrastructure. If you have trouble getting any of the other options to work, use this.

Login to 'dsmlp-login.ucsd.edu' (our primary student Linux SSH server) using you normal student login.

Run the command `launch-142` to connect to a remote Docker container running the development environment image.

Here's a transcript of the login process for user `cs142lsp21zz`:

$ ssh [e-mail]
To see all available software packages, type "prep -l" at the command prompt,
or "prep -h" for more options.
============================ NOTICE =================================
Authorized use of this system is limited to password-authenticated
usernames which are issued to individuals and are for the sole use of
the person to whom they are issued.

Privacy notice: be aware that computer files, electronic mail and 
accounts are not private in an absolute sense.  You are responsible
for adhering to the ETS Acceptable Use Policies, which you can review at:
https://blink.ucsd.edu/faculty/instruction/tech-guide/policies/ets-acceptable-use-policies.html
=====================================================================

*** Data Science and Machine Learning Platform Resources ***
    
    How to Launch Containers From the Command Line: 
    https://support.ucsd.edu/services?id=kb_article_view&sysparm_article=KB0032269

    How to Select and Configure Your Container:
    https://support.ucsd.edu/services?id=kb_article_view&sysparm_article=KB0032273

    Building Your Own Custom Image:
    https://github.com/ucsd-ets/datahub-example-notebook

    Your instructor or TA will be your best resource for course-specific questions.
    
    If you still have questions or need additional assistance, please email [e-mail] 
    to create a support ticket.


-------------------------------------------------------

quota: No filesystem specified.
Hello cs142lsp21zz, you are currently logged into dsmlp-login.ucsd.edu

You are using 0% CPU on this system

[cs142lsp21zz@dsmlp-login]:~:1$ launch-142
Attempting to create job ('pod') with 4 CPU cores, 16 GB RAM, and 0 GPU units.
   (Adjust command line options, or edit "/software/common64/dsmlp/bin/launch-142.sh" to change this configuration.)
pod/cs142lsp21zz-1435 created
Sat Apr 3 16:40:17 PDT 2021 starting up - pod status: Pending ; Successfully assigned cs142lsp21zz/cs142lsp21zz-1435 to its-dsmlp-n25.ucsd.edu
Sat Apr 3 16:40:23 PDT 2021 pod is running with IP: 10.40.224.4 on node: its-dsmlp-n25.ucsd.edu
ucsdnvsl/cse141pp:latest is now active.

Connected to cs142lsp21zz-1435; type 'exit' to terminate pod/processes.
/course/CSE141pp-Config ~
cat: /course/CSE141pp-Config/secrets/packet_auth_token: No such file or directory
Welcome to the archlab development environment!
STUDENT_MODE enabled
THIS_DOCKER_IMAGE=ucsdnvsl/cse141pp:sp21.142
IN_DEPLOYMENT=DEPLOYED
CLOUD_MODE=CLOUD
[cs142lsp21zz@dsmlp-login]:~:2$

To make sure everything is working, you can run `runlab --help`. You should get this:

cs142lsp21zz@cs142lsp21zz-10005:~$ runlab --help
usage: runlab [-h] [-v] [--pristine] [--info [INFO]] [--no-validate] ...

Run a Lab

    Running the lab with this command ensure that your compilation and
    execution enviroment matches the autograder's as closely as possible.

    Useful options include:

    * '--no-validate' to run your code without committing it.
    * '--info' to see the parameters for the current lab.
    * '--pristine' to (as near as possible) exactly mimic how the autograder runs code.

positional arguments:
  command        Command to run (optional). By default, it'll run the command
                 in lab.py.

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  Be verbose
  --pristine     Clone a new copy of the reference repo.
  --info [INFO]  Print information about this lab an exit. With an argument
                 print that field of lab structure.
  --no-validate  Don't check for erroneously edited files.
cs142lsp21zz@cs142lsp21zz-10005:~$

If you go this route, you can skip instructions below regarding running `docker` directly.

You can then clone your repo in the directory that you land in and work on it.

Your files inside the `launch-142` environment are stored in this system: https://datahub.ucsd.edu/hub/login.

## Get a Copy of the Starter Code

First, accept the assignement on Github Classroom. It's available via the 142L lab home page (you can find it via Canvas).

This will set you up with a copy of the starter repository.

Use `git clone` to clone your repo locally.

There are a few files:

- `code.cpp` -- the code you'll modify.
- `main.cpp` -- The "driver" code that calls the code in `code.cpp`.
- `config.env` -- a configuration file you can use to control how your code is built and run on the autograder.
- `Makefile` -- The makefile for the lab. It builds `code.exe`
- `lab.py` -- A python file that configures the lab.

You should only modify `code.cpp` and `config.env`. Changes to the other files __will not affect how things run on the autograder__ but they will affect how things run locally. If you change them, your local results will not match the autograder results, which will probably be confusing.

## Test the Starter Code Locally

**TODO** have them include a screen cap and cut the need to commit the file. Both are kind of silly, but we just need to make them go through the steps.

In the example commands that follow, we'll assume your github username is `stevenjswanson`.

Navigate to
`/home/sp21-CSE142L-intro-stevenjswanson` and
run `runlab`. This will compile the starter code into
`code.exe` and run it.

You can compile and run `code.exe` directly, but using `runlab` mimics how your
code will be run on the autograder, so it's a good idea to use it.

The output will be pretty long, but in middle somewher it should say
"Hello, world!".

Save the output of `code.exe` as `outputs/starter-output.txt` and
commit to Github:

git add outputs/starter-output.txt
git commit -m 'starter output'
git push

## Modify the Starter Code

**TODO** Same as above. Hve them turn in a screen cap of what would have ended up in `modified_output.txt`. They don't need to create the file or commit it.

Open up `code.cpp`. The function `greet()' takes two arguments, a name and a
salutation (e.g., "Hello", "Good morning").

Modify the function to output "<salutation>, <name>!" using those variables (e.g., "Hello, Ada!") instead of "Hello, world!".

It's C++, so you should use `std::cout` and the `<<` opererator.

Try to test it:

runlab

Uh oh!:

  code.cpp  | 1 +
  1 files changed, 1 insertions(+), 1 deletion(-)
  ERROR    You have uncommitted changes and/or there is changes in github that you don't have locally.  This means local behavior won't match what the autograder will do.
  ERROR    To run anyway, pass '--no-validate'.  Alternately, to mimic the autograder as closely as possible (and require committing your files), do '--pristine'

`runlab` is telling you that the local doesn't match what you've
checked in, so the results you get here won't match what the
autograder will see. That's ok, since we are still testing, so just do

runlab --no-validate

You should see the output change to `Howdy, Ada!`.

Push your changes and the output to Github:

git add code.cpp outputs/modified-output.txt
git commit -m 'personalized greeting'
git push

Now, `runlab` should work without `--no-validate`. Verify that it does.

## Controlling How the Code Runs

**TODO** Same thing. Screen cap. don't commit the results. Make it as easy as possibel for them to demonstrate that they did the steps.

There are factors besides the source code that affect how a program behaves.
You can set these via the `config` file. `runlab` reads this file to configure
your experiment.

If you open `config.env` you'll see two line:

EXTRA_OPTIONS=
salutation=

`EXTRA_OPTIONS` lets you pass command line options to `code.exe`. In this
case, we set the name by passing `--name` (e.g., `EXTRA_OPTIONS=--name Steven`).

`salutation` is a lab-specific configuration option. A value of
`formal` (i.e., `salutation=formal`) will set the salutation to
"greetings". You can see the available lab-specific options and
values with `runlab --info` (try it!).

Edit `config.env` to change the salutation to `short` and make it print
your name, and run your code again with

runlab  --no-validate

You should see those change reflected in the output (e.g., `hi,
Steven`). Once you have the settings to your liking, commit them.

**NOTE**: You may be tempted to try to add them to `Makefile` instead
of `config`, since there are commandline options in there as well.
However, the autograder ignores the `Makefile` in your
repo, so changes there will have no effect on what runs on the
autograder.

## Running Code on our Bare Metal Machines

Some parts of your assignments will need to run on bare metal servers in the cloud. There are two reasons for this:

1. These machines are not shared with anything else, so you can get clean performance measurements.
2. Some of our experiments require access to processor performance counters, which require elevated priviliges.

During development and testing, you'll use `runlab` to submit jobs to the bare metal servers. When you are done, you'll submit your code via Gradescope, which will perform final grading using the same servers.

### Running Code In the Cloud with `runlab`

To can run your code in the cloud like so:

runlab --run-git-remotely

This will checkout your git repo on the cloud machine, run it, and ship results back to you.

You can also run specific `make` targets. For instance, this will run `make default` on the servers:

runlab --run-git-remotely -- make default

### Running Code Through GradeScope

The Gradescope autograder is able to run more tests on your code on
our reference processor. In this lab we will measure execution time
and energy.

1. Log into Gradescope.
2. Click on your section of 142L.
3. Click `Introduction to the development environment`.
4. Click `Submit` (bottom right).
5. Select `Github`
6. Enter the name of your repo (e.g., `sp21-CSE142L-intro-stevenjswanson')
7. Select the `master` branch.
8. Click `Upload`

The first contains the `stdout` and `stderr` of your code.

Then, there are several sections that represent different parts of the
assignment. Each of them has a score associated with it, but many of
them are labeled "0.0/0.0". This means the box just contains some
information is not a graded part of the assignment.

If a box has a non-zero denominator, then it is actually graded (see the rubric below).

The first box has a url for a zip file with the outputs of this run.
Paste it into a web browser (you may need to log into google), open it, and
you'll find all the inputs and outputs for lab.

After the URL are the graded sections of the lab. Here, you'll see
one "question" corresponding to each of the files we asked you to save
during the lab.

Finally, there's some JSON that has some information that might be
useful to course staff in debugging an problems that you have.

## When You Are Done

You can resubmit as many times as you'd like. We'll use the latest submit before the deadline.

# PART II: SOMETHING!