PROJECT: Introductory Activities and Getting Started (ntr0)
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.
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”
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:
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.
This document is written with TWO locations in mind:
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:
Please pay attention to your prompt, so you can perform the needed activity on the correct system.
Be sure to have a handle on these things before proceeding on:
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.
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.
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.
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:~$
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.
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
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:
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:~$
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.
Through various course activities, you may need to install additional software on your Raspberry Pi. Here are some instructions on how to do that.
yourpi:~$ sudo apt-get update
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.
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
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).
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.
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:
/* * 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.
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
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.
When Clicking on your journal link:
Familiarize yourself with your Journal, and once there:
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
To be successful in this project, the following criteria must be met:
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: