======PROJECT======
PROJECT: Introductory Activities and Getting Started (ntr0)

=====Objective=====
In this project, we get started with some course initialization activities.

The aim is to:

  * get you settled and configured with pertinent class resources
  * test your ability to parse and proceed through linear, top-down documentation
  * generate contextual awareness of your place within the computing environment
  * start to acclimate to variables and conditions of abstraction

All of which will be important, ongoing skills to possess and continue to strengthen as we proceed through the course.

=====How to proceed through this project=====
There has been some unexpected confusion by some on how to glean information and make progress through this project (ie the information contained within this document and the necessary actions and awareness of what is going on).

The following advice, when genuinely followed, seems to remedy any initial confusion:

  * read through this document, starting at its very top, and working your way down, line by line to the bottom (it is generally linear, with contextual clues sprinkled in)
  * as you read through, comprehend and strive to understand what is happening. The supporting text, often surrounding any example or model commands to run, will tend to fill in the crucial backstory and connections. If further clarification is needed, please ask questions! Just running the commands in this document and having ZERO clue of what you are doing isn't going to help you in the long run.
  * have a contextual/locational awareness of where you are (there are 2 different computing systems you are to perform work on, and there are two different means of accessing one of the systems- via command line, and via the web)
  * we will be making heavy use of abstraction in this course. We start off with some simple exercises, providing you with model commands you need to adjust to fit your reality (ie commands that won't work as literally shown, but when pertinent meanings are substituted in and followed, will result in success: this is a common theme throughout the course).
  * remember (for the duration of the course) the important concepts presented: for this project will NOT be the last time you see them. Starting from a clean slate each project, retaining NOTHING from your prior experiences will make things unnecessarily difficult for you.
  * be sure to spend some time experimenting and playing, so as to gain an even deeper understanding and familiarity with these concepts. We will encounter and use many tools that facilitate our means of accomplishing various tasks. Their application isn't necessarily limited to the current activity of the project or the subject matter of the course. There are a wealth of productivity treasures to be encountered (both tangible and intangible) that can supercharge your educational journey.

As many of my graduated and subsequently employed alumni have relayed to me, many of these activities and behaviours I have highlighted have been quite influential in their success at their various jobs.

Say some of my former students now employed: "Reading is 90%+ of the job"

=====Abstraction=====
{{page>haas:spring2022:common:projects:abstraction&noheader}}

=====Locational Awareness=====
{{page>haas:spring2022:common:projects:location&noheader}}

=====Part 1: Getting started with course resources=====
Be sure to have a handle on these things before proceeding on:

====Reading====
Please be sure to read through, play with, and comprehend the material in the PDF "UNIX for the Beginning Mage":

  * https://lab46.g7n.org/_media/haas/ufbm.pdf ([[https://acrobat.adobe.com/us/en/acrobat/pdf-reader.html|Download PDF viewer]])

This will introduce you to some important computing tools which we will be using to facilitate our class activities this semester. Especially if you haven't had much exposure to "files" on the computer and their organization and manipulation. You really need to have this material down.

====Class Discord====
One of the very **FIRST** things you should do is get situated on the class discord. Your classmates are there, as are others who can offer you insight and help should you need it while navigating the steps of this project.

When you join the discord for the first time, please indicate what classes you are in (for example, "I am taking 'cprog' and 'unix'"; or "I am taking 'comporg'"). Then you will be added to the appropriate role and be able to utilize the class-specific discord.

====Course Homepage/Syllabus====
You're reading this, so you've likely already found your way to the course homepage. It consists of the syllabus plus additional course resources.

Please familiarize yourself with it, bookmarking important resources as appropriate, so that you can refer back when needed.

I'd recommend knowing how to get to the projects page (where you found the link for this project), as new content will be posted there. Note the due dates and identify the current and upcoming projects.

Be sure to read through and over the syllabus, ensuring there are no questions on the material and organization of the course.

=====Part 2: logging onto Lab46 command-line=====

====Lab46 Shell====
For many of you, this will be your first experience logging onto Lab46 and working within a command-line environment.

To access lab46, you will need to SSH or MOSH into **lab46.g7n.org**; here is a document that provides some further information on the correct login process (and some troubleshooting steps):

  * [[/haas/spring2022/common/helpances/loginissues|Logging into Lab46]]

Your clearest indication you are on lab46 will likely be in the display of the prompt, resembling (in whole or in part) the following:

<cli>
lab46:~$ 
</cli>

====Clone your Lab46 Mercurial Repository on lab46====
**__NOTE:__** Even if you have done this in a prior semester, you WILL need to do it again (once per semester), as there are now per-semester repositories.

To both aid you and help you develop better development skills, I'd like for you to make regular commits and pushes to your semester Lab46 mercurial repository.

This way, you can have a regular snapshot of your work as you go along, plus have the ability to grab an older copy should something go wrong.

Like the Journal, I will be looking for a minimal amount of repository-related activity PER WEEK.

To set up your repository, run the "fixrepo" script:

<cli>
lab46:~$ fixrepo
</cli>

NOTE: you ONLY want to run 'fixrepo' once per semester to get things set up, to take you from a state of not having an established repository on lab46, to the state of having a cloned and readied repository on lab46. Running it again could "refresh" things to this state, potentially moving unadded/uncommitted/unpushed somewhere else and causing you confusion.

For basic repository operation, when you make new files you'd like to track, or see the status of any tracked files that have changed:

<cli>
lab46:~$ cd src
lab46:~/src$ ls
SEMESTER
lab46:~/src$ cd SEMESTER
lab46:~/src/SEMESTER$ hg status
A .hgignore
lab46:~/src/SEMESTER$ 
</cli>

Once cloned (to your ~/src/SEMESTER directory), you will be able to add, commit, and push changes made:

<cli>
lab46:~/src/SEMESTER$ hg add
lab46:~/src/SEMESTER$ hg commit -m "brief message describing the changes"
lab46:~/src/SEMESTER$ hg push
</cli>

On the push, you will be prompted to provide your lab46 password.

And that's it! Repeat this process (NOT the 'fixrepo'; only do that once) for any changes you make to your repository.

===Grab the 'ntr0' project on lab46===
There are files prepared to help you get through the **ntr0** project. While you are still logged into lab46 (and have successfully cloned your semester repository), you can 'grab' the files with the use of the 'grabit' command:

<cli>
lab46:~$ cd ~/src/SEMESTER
lab46:~/src/SEMESTER$ mkdir DESIG
lab46:~/src/SEMESTER$ cd DESIG
lab46:~/src/SEMESTER/DESIG$ grabit DESIG ntr0
</cli>

You will want to add/commit/push these new files to your semester repository, so that you can retrieve c4engthem on your pi to continue working on them:

<cli>
lab46:~/src/SEMESTER/DESIG$ hg add
...
lab46:~/src/SEMESTER/DESIG$ hg commit -m "adding ntr0 project files"
lab46:~/src/SEMESTER/DESIG$ hg push
</cli>
=====Part 3: Getting started on the Raspberry Pi=====
The pi-related activities on this project require you to have a Raspberry Pi single board computer, assembled and operational, running the 32-bit Raspberry Pi OS (aka raspbian).

The aim is that you will use your pi, your personal linux box, for working on coursework.

NOTE: on your pi, your default username and password are:

  * username: **pi**
  * password: **raspberry**

====The Shell (command-line) on the pi====
For many of you, this will be your first experience logging onto a Raspberry Pi and working within a command-line environment. You're taking your first steps into a much larger world.

Your clearest indication you are on your Raspberry Pi will likely be in the display of the prompt, resembling the following (in whole or in part):

<cli>
pi@raspberry:~$ 
</cli>

For the purposes of instruction, I will represent this prompt as:

<cli>
yourpi:~$ 
</cli>

====Change your pi password====
It might be a prudent idea to change the password for your **pi** user. You can do that with the **passwd** command, run at your pi prompt:

<cli>
yourpi:~$ passwd
</cli>

NOTE: you will NOT see ANYTHING when you type in your password.

====Manage Packages====
Through various course activities, you may need to install additional software on your Raspberry Pi. Here are some instructions on how to do that.

===Step One: Update your package database===
<cli>
yourpi:~$ sudo apt-get update
</cli>

===Step Two: Apply any updates===
<cli>
yourpi:~$ sudo apt-get upgrade
</cli>

NOTE: As a good general practice, you may want to perform the "update" and "upgrade" steps on a somewhat regular basis.

===Step Three: Search for packages===
If you do not know the exact name of a given package, you can attempt to search for it. 

For example, if you've heard about a really neat terminal-based frontend to apt-get/apt-cache called "aptitude", and want to know the correct package name so you can install it:

<cli>
yourpi:~$ apt-cache search aptit
aptitude - terminal-based package manager
aptitude-common - architecture independent files for the aptitude package manager
aptitude-doc-en - English manual for aptitude, a terminal-based package manager
libcwidget-dev - high-level terminal interface library for C++ (development files)
apt-cacher - Caching proxy server for Debian/Ubuntu software repositories
apticron - Simple tool to mail about pending package updates - cron version
apticron-systemd - Simple tool to mail about pending package updates - systemd version
aptitude-doc-cs - Czech manual for aptitude, a terminal-based package manager
aptitude-doc-es - Spanish manual for aptitude, a terminal-based package manager
aptitude-doc-fi - Finnish manual for aptitude, a terminal-based package manager
aptitude-doc-fr - French manual for aptitude, a terminal-based package manager
aptitude-doc-it - Italian manual for aptitude, a terminal-based package manager
aptitude-doc-ja - Japanese manual for aptitude, a terminal-based package manager
aptitude-doc-nl - Dutch manual for aptitude, a terminal-based package manager
aptitude-doc-ru - Russian manual for aptitude, a terminal-based package manager
aptitude-robot - Automate package choice management
cron-apt - automatic update of packages using apt-get
cupt - flexible package manager -- console interface
gbrainy - brain teaser game and trainer to have fun and to keep your brain trained
pkgsync - automated package list synchronization
wajig - unified package management front-end for Debian
</cli>

You may get a lot of packages listed. Read through the output (package name on left, brief description on right). Turns out, in this case, the very package we want is the first one listed: **aptitude**

===Step Four: install specified packages===
<cli>
yourpi:~$ sudo apt-get install aptitude
</cli>

NOTE: With the installation of **aptitude**, you can use it in place of apt-get/apt-cache:

  * update: **sudo aptitude update**
  * upgrade: **sudo aptitude upgrade**
  * search: **aptitude search __TOKEN__**
  * install: **sudo aptitude install __PACKAGE__**

Where **__TOKEN__** is some substring of the thing you are looking for, and **__PACKAGE__** is the name of the installable package.

Some other packages (substitute in place of **__PACKAGE__** above) you might want to install (some might already be installed):

  * bc
  * screen
  * wget
  * less
  * mosh
  * file

Be on the lookout for other packages to install in this project (often embedded in the reading or unhighlighted on various lists of actions to take).

====Clone your Lab46 Mercurial Repository on your raspberry pi====
**__NOTE:__** If you have already done this on your pi (such as in a previous semester), you WILL need to do it again, because we now have per-semester mercurial repositories.

Because we will be juggling our activities between lab46 and your raspberry pi (ideally doing the bulk of the work on the pi, then transferring it to lab46 to submit), you will also want to clone your repository on your pi.

I have created a script that will facilitate this, all you have to do is log onto your pi, download the script, and execute it (providing valid information as it requests):

<cli>
yourpi:~$ wget -q https://lab46.g7n.org/~wedge/piph/download -O piph
yourpi:~$ bash ./piph
</cli>

NOTE: The above snippet scrolls to the right. Make sure you type in everything.

NOTE NOTE: if something doesn't seem to work (like when you run it and nothing happens), try the wget **without** the <nowiki>-q</nowiki>. If it talks about a certificate being untrusted or expired, in place of the <nowiki>-q</nowiki>, instead use:

  * **<nowiki>--no-check-certificate</nowiki>** to get it downloaded.

When running piph, you may be prompted for authentication. It is your (ssh) lab46 account and password. But pay attention to the on-screen prompts, they ask for different bits of information.
====Program to Implement====
As a first week exercise, I would like you to implement, successfully compile, and verify correct execution of the best first program every great programmer writes: **Hello World**

  * You will want to ensure a compiler is installed on your raspberry pi. Install the "build-essential" package to accomplish this.

Code will be as follows:

<code c 1>
/*
 * hello.c - the first best C program ever
 *
 * written by: your name
 */
#include <stdio.h>

int main()                              // every program needs a start, main() is ours
{
    fprintf(stdout, "Hello, World!\n"); // display a message to STDOUT
    return (0);                         // return a success status to OS
}
</code>

Your task will be to transcribe this code into a source file (call it **hello.c** for simplicity), within the pertinent SEMESTER subdirectory of your lab46 account (**~/src/SEMESTER/DESIG/ntr0/** would be the ideal choice).

You should have already established the ~/src/SEMESTER/DESIG/ntr0 directory when you cloned your repository in the previous section. Make sure you have successfully done that before you proceed (ie if, when you run the following **cd** command you get an error, investigate it)

<cli>
yourpi:~$ cd ~/src/SEMESTER/DESIG/ntr0
yourpi:~/src/SEMESTER/DESIG/ntr0$ 
</cli>

NOTE: "DESIG" is your class designation ("cprog", "unix", "data", "discrete", "c4eng", etc.) Do NOT literally type D-E-S-I-G.

Similarly, "SEMESTER" is the current semester (such as "spring20XY" or "fall20XY"), do NOT literally type S-E-M-E-S-T-E-R.

If there are no files in this **ntr0** subdirectory, AND you have successfully cloned your repository onto your pi, you may need to pull/update changes:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg pull; hg update
</cli>

You may want to use the **nano** text editor to edit your program source:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ nano hello.c
</cli>

The **nano** text editor is a simple editor that provides basic functionality (commands listed at the bottom of the screen. You press the CONTROL key in combination with whatever letter invokes the desired functionality).

To save the file: CTRL+o (and hit ENTER to save the file with its current name)

To save and exit (or exit if there are no unsaved changes): CTRL+x

Note that if there are any changes, you will be prompted whether or not you'd like to save them (the changes are in memory (aka the buffer), and nano will prompt if you'd like to save the modified buffer). You will then be prompted for the filename (filling in the current filename, if there is one). Just press enter to accept these changes.

To see if you typed everything correctly, type **make** at the prompt.

If you type **make run** you should see it display "Hello, World!"

When that is all said and done, you'll want to update your repository with your changes. To avoid unnecessary conflicts, you should ALWAYS check for incoming changes before you try and commit new changes:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg pull; hg update
</cli>

With that out of the way, you can proceed to adding/committing/pushing your changes.

Whenever you make a new file you wish for mercurial to track, you will first need to "add" it:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg add hello.c
</cli>

You can then commit the current snapshot of it:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg commit -m "adding hello.c"
</cli>

And finally, pushing it to the server:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg push
</cli>

If there are any errors or additional changes to be made, make them, and then do a follow-up "commit" and "push". Ideally you will want to make several commits per file per project, capturing your implementation progress (the more snapshots you make, the more points of restoration will exist to you should you need to backtrack).

Once satisfied, be sure to submit the program source code and binaries as indicated below.

====Information====
As part of routine housekeeping tasks to kick off the course, I would like for you to provide me (ie submit) a text file (called **info.text**) that contains the following information (each on a line by itself, shared only with its heading):

  * Your preferred name or nickname (after the heading "name: ")
  * Your preferred (and frequently checked) e-mail (after the heading "email: ")
  * Your discord screen name (they aren't always easy to intuit, after the heading "discord: ") 
  * Your matriculated program of study (after the heading "program: ")
  * Any other information you feel pertinent to tell me (after the heading "other: ")

<cli>
yourpi:~$ cd ~/src/SEMESTER/DESIG/ntr0
yourpi:~/src/SEMESTER/DESIG/ntr0$ 
</cli>

If you have grabbed the **ntr0** project on lab46, and pulled/updated it on your pi, you can run the **setup** script to facilitate the recording of this information:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ ./setup
</cli>

Whenever you make a new file you wish for mercurial to track, you will first need to "add" it:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg add info.text
</cli>

You can then commit the current snapshot of it:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg commit -m "adding info.txt for ntr0"
</cli>

And finally, pushing it to the server:

<cli>
yourpi:~/src/SEMESTER/DESIG/ntr0$ hg push
</cli>

=====Part 4: Accessing your website-based class resources=====

====Wiki====
The course homepage/syllabus, your journal, and other resources are made available to you via the lab46 wiki. In order to better access your web resources for the course, you must log in:

  * top right of this page, notice the "login" button
    * sign in with your wiki username (should be same as lab46 login) and password
    * your wiki password should be in an e-mail to you on lab46
      * run the '**getwikipass**' command and interpret the output to assist you on your next action.
      * failing that, you can attempt to use the 'alpine' command when logged into lab46 to retrieve your wiki password (you can ask for help about this in the class discord)
  * once logged in (to the wiki), note the left sidebar has been updated with some custom (to you) content
    * links to the course homepages of the classes you are taking with me
    * a link to your journal

Go ahead and familiarize yourself with these resources.

====Journal Intro====
When Clicking on your journal link:

Familiarize yourself with your Journal, and once there:
  * customize it (title/subtitle, as you feel fitting. Change "YOUR NAME" to your actual name, etc.)
  * add an introduction (tell us a little something about yourself)
  * create your first week content

=====Part 5: Getting data from your pi to lab46=====
So, you've written a C program and a text file. Both of which need to be submitted on lab46. How do we get data from your pi to lab46? If you've added it to your repository, we use that!

<cli>
lab46:~/src/SEMESTER$ hg pull; hg update
</cli>

Similarly, if you want to get something originally on lab46 to your pi, add/commit/push it to your repository, then on your pi, do the same pull/update command.

Make sure you've pushed any and all commits before you do this, though!

Once your changes have been pulled back and updated on your lab46 copy, go into your **ntr0** directory on lab46 and run **make** once again (this will compile your code on lab46). You'll notice you should then have TWO (green) hello binaries: hello.x86_64 and hello.armv7l

=====Part 6: Submission of the project=====
To be successful in this project, the following criteria must be met:

  * Project must be submit on time, by the posted deadline to be eligible for full credit.
    * Late submissions will lose 33% credit per day, with the submission window closing on the 3rd day following the deadline.
    * Early submissions can earn at least one bonus point per day in advance of the posted due date.
  * All code must compile cleanly (no warnings or errors)
    * all requested functions must be implemented in the related library or program
    * all requested functionality must conform to stated requirements (either on this project page or in comment banner in source code files themselves).
  * Executed programs must display in a manner similar to provided output
    * output formatted, where applicable, must match that of project requirements
  * Processing must be correct based on input given and output requested
  * Output, if applicable, must be correct based on values input
  * Code must be commented
    * Any "to be implemented" comments **MUST** be removed
      * these "to be implemented" comments, if still present at evaluation time, will result in points being deducted.
    * Sufficient comments explaining the point of provided logic **MUST** be present
  * Track/version the source code in a repository
  * Submit a copy of your source code to me using the **submit** tool by the deadline.
  * Make sure your submitted source code is in a file called **hello.c**
  * Make sure it outputs exactly like the sample output above.
  * Create and submit a text file called **info.text** that contains the requested information

====Submit Tool Usage====
Let's say you have completed work on the project, and are ready to submit, hop over to lab46, do any needed repository retrieval, navigate to your project directory, and (exercising appropriate substitution), do the following:

<cli>
lab46:~/src/SEMESTER/DESIG/ntr0$ make submit
Submitting DESIG project "ntr0":
    -> ntr0-DATESTAMP.tar.gz(OK)

SUCCESSFULLY SUBMITTED
lab46:~/src/SEMESTER/DESIG/ntr0$ 
</cli>

You should get some sort of confirmation indicating successful submission if all went according to plan. If not, check for typos and or locational mismatches.

I'll be evaluating the project based on the following criteria:

<code>
13:ntr0:final tally of results (13/13)
*:ntr0:customized journal (title and intro) [1/1]
*:ntr0:joined discord chat [1/1]
*:ntr0:submitted proper info.text file [1/1]
*:ntr0:cloned lab46 mercurial repository into ~/src [1/1]
*:ntr0:cloned lab46 semester repository into ~/src/SEMESTER [1/1]
*:ntr0:submitted file called hello.c [1/1]
*:ntr0:committed, pushed hello and info files to semester repo [1/1]
*:ntr0:adequate commenting and indentation in hello.c [1/1]
*:ntr0:executable runs without issue [1/1]
*:ntr0:submits executables from two architectures [1/1]
*:ntr0:output conforms to project specifications [1/1]
*:ntr0:adequate modifications in hello.c [1/1]
*:ntr0:no compiler messages for hello.c [1/1]
</code>

Additionally:
  * Solutions not abiding by spirit of project will be subject to a 25% overall deduction
  * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
  * Solutions not utilizing indentation to promote scope and clarity will be subject to a 25% overall deduction
  * Solutions not organized and easy to read (assume a terminal at least 90 characters wide, 40 characters tall) are subject to a 25% overall deduction