Table of Contents

PROJECT

PROJECT: Introductory Activities and Getting Started (ntr0)

Objective

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

The aim is to:

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:

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

As an exercise in toning your abstraction abilities (literally seeing one thing, but understanding and using it as something else), there will be a number of 'generic' terms used throughout this (and other) documents throughout the course, requiring you to substitute in the pertinent information (else face confusion or error).

Some examples:

  • yourusername - where you see this (likely in a config file or command-line argument), you are NOT to literally type in y-o-u-r-u-s-e-r-n-a-m-e, but instead, substitute in YOUR lab46 username.
  • desig - different classes have different class designations. To make one universal document pertinent to ALL classes, specific examples will instead use 'desig', where you must substitute in the class desig of the class YOU are taking and acting upon in that moment. Example class desigs:
    • c4eng - ENGR1050 “C for Engineers”
    • cprog - CSCS1320 “C/C++ Programming”
    • unix - CSCS1730 “UNIX/Linux Fundamentals”
    • data - CSCS2320 “Data Structures”
    • discrete - CSCS2330 “Discrete Structures”
    • comporg - CSCS2650 “Computer Organization”
    • sysprog - CSCS2730 “Systems Programming”

This sort of abstraction is very similar to that we will find in our utilization of variables in programming, where we can have a “name”, but the data associated with it can change based on various conditions.

Do not be a literalist computer! Start to exercise your abstraction abilities.

2023/01/18 11:37

Locational Awareness

This document is written with TWO locations in mind:

  • lab46 (the system you may retrieve resources and SUBMIT projects)
    • identified in examples with the use of the lab46:~$ prompt
  • your pi (the system you will transfer resources to/from, and WORK ON/COMPLETE projects)
    • identified in examples with the use of the yourpi:~$ prompt

There are commands you can ONLY run on one system or the other. Pay attention to any prompt cues in the given examples (or section headings, context of language leading up to any examples).

For example:

  • YOU cannot install software on lab46. You don't have access.
  • projects CANNOT be SUBMITTED on your pi.

Please pay attention to your prompt, so you can perform the needed activity on the correct system.

2023/01/18 11:37

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”:

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 class-interactive actionable 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, and other projects this semester.

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.

Do note: by identifying the class(es) you are in, you will likely earn your first week participation points. Don't just join and remain silent: you will miss out on points.

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):

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

lab46:~$ 

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:

lab46:~$ fixrepo

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:

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

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

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

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:

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

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:

lab46:~/src/SEMESTER/DESIG$ hg add
...
lab46:~/src/SEMESTER/DESIG$ hg commit -m "adding ntr0 project files"
lab46:~/src/SEMESTER/DESIG$ hg push

Part 3: Getting started on your Raspberry Pi/system

NOTE: while the wording may refer to a “raspberry pi”, due to current supply chain constraints, feasible accessibility to such may not be viable. As a result, I am allowing you to either have a pi for use in the class, or your own dedicated linux system that you can install software on and risk breaking.

The pi-related activities on this project are optimized around you having 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:

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):

pi@raspberry:~$ 

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

yourpi:~$ 

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:

yourpi:~$ passwd

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

yourpi:~$ sudo apt-get update

Step Two: Apply any updates

yourpi:~$ sudo apt-get upgrade

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:

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

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

yourpi:~$ sudo apt-get install aptitude

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

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):

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):

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

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 -q. If it talks about a certificate being untrusted or expired, in place of the -q, instead use:

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

Code will be as follows:

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
}

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)

yourpi:~$ cd ~/src/SEMESTER/DESIG/ntr0
yourpi:~/src/SEMESTER/DESIG/ntr0$ 

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:

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

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

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

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:

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

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:

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

You can then commit the current snapshot of it:

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

And finally, pushing it to the server:

yourpi:~/src/SEMESTER/DESIG/ntr0$ hg push

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):

yourpi:~$ cd ~/src/SEMESTER/DESIG/ntr0
yourpi:~/src/SEMESTER/DESIG/ntr0$ 

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:

yourpi:~/src/SEMESTER/DESIG/ntr0$ ./setup

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

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

You can then commit the current snapshot of it:

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

And finally, pushing it to the server:

yourpi:~/src/SEMESTER/DESIG/ntr0$ hg push

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:

Go ahead and familiarize yourself with these resources.

Journal Intro

When Clicking on your journal link:

Familiarize yourself with your Journal, and once there:

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!

lab46:~/src/SEMESTER$ hg pull; hg update

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:

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:

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

SUCCESSFULLY SUBMITTED
lab46:~/src/SEMESTER/DESIG/ntr0$ 

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:

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]

Additionally: