a00 Setup

DUE: 2022-01-21T00:00:00-5:00

The purpose of this is assignment is to get familiar with the tools that we will be using in COMP 426 for the rest of the semester as well as the assignment submission process.

Note that this first assignment, a00, is graded only for general completion. Future assignments will be much deeper in scope, and you should expect to spend significantly more time on them.

Install Required Software

Below are links to guides for installing the required software for this course. It is all free software and it is mostly open source software, with the exception of Chrome. Chrome is built on the Google’s open source Chromium code base, BUT Chrome itself is licensed as proprietary software.

You are not expected to purchase software for this course.

This software must be installed on your computer not only so you can complete the assignments, but also so you can receive help in office hours.

You will be installing the following:

  1. Chrome (web browser)
  2. Node.js (Javascript Runtime)
  3. git (version control/wofkflow management)
  4. bash (command shell) - Windows users will need to install the Windows Subsystem for Linux. MacOS and Linux users will already have this installed.
  5. VSCode / VIM (text editor)

You do not have to use a specific text editor for this class. HOWEVER, you should use a code editor that has good syntax highlighting.

I encourage you to install and learn VIM in addition to or instead of VSCode.

Visual Studio Code is recommended for COMP 426 as it is installable cross-platform and is also configured as the default IDE for our GitHub classroom assignments.

Whenever you are installing software for development purposes, you should pay attention to version and backward compatibility.

Understand the difference between current or latest versions and the Long Term Support (LTS) versions of packages you are using.

In this course we will use the current Node LTS version 16.13.2 (LTS). Node flipped from 14 as the LTS version to 16 in November 2021, so some techniques might need adapting but we will deal with that as it comes.

My recommendation is that you use a Node version manager of some kind to install and manage Node. It makes knowing what version you are using and keeping it up-to-date a lot easier.

A note on installing software

I am not going to labor over teaching you to install software in this class.

You are in a programming class. It is my expectation that you have, at the very minimum, the ability to understand how to install and configure software.

The instructional staff is happy to help you if you run into snags, but bear in mind that before you come to us with questions related to software installation and management, you should have exhausted all available resources in the form of documentation and reading (and Googling) error messages, etc.

This is your first opportunity for a bit of “Physician, healh thyself,” in this class.

You can do these things. You can FIGURE OUT HOW to do these things.

I believe in you.

Windows

If you are running Windows, follow the Windows setup guide.

REMEMBER: if you are using Windows, it is super important that you pay special attention to installing the Windows Subsystem for Linux.

This will allow you to run a Linux development environment, which is hugely helpful to you as a skill, and also makes teaching this course more straightforward, because everyone will have access to a UNIX-like system to develop on.

Mac

If you have a Mac running OSX, follow the Mac setup guide.

Linux

If you run Linux, and you don’t already have the above list installed, you can follow the Linux setup guide.

Join GitHub classroom

  1. Make sure you are logged into GitHub: https://github.com/login If you do not have a GitHub account, then create one and log in.
  2. Use the assignment link for this assignment: https://classroom.github.com/a/V3VIssyS.a
  3. On the next page, click the green button that says “Accept this assignment.”
  4. Read the text on the page that follows. It will say that it is configuring your repository and that you should refresh the page.
  5. Refresh the page.
  6. You will now see a page that shows a link to your repository. NB: This repository doesn’t exist under your GH account directly, but under the “organization” that owns the GitHub Classroom (jdmar3-comp426).
  7. Open the link to your repository page for a00, which should have the form of https://github.com/jdmar3-comp426/a00-$YOURGITHUBUSERNAME.

Set Up Workspace

Now that you have installed all the preqrequisite software and joined our GitHub classroom, you can create your workspace and organize yourself for class.

Our recommendation is that you create a directory called “comp426” or something similar which you will use to keep all of your work in.

You will have a repository for each assignment and so you can use this directory to clone all of your repos into.

Some of the assignments have their own starter code and some are just blank repos that you will commit your code to and then push back up to GitHub.

Clone the starter code repo

There are multiple ways to clone a repo and get yourself up and running.

Below we will detail doing this in VSCode and in a Bash shell.

VSCode

  1. Open Visual Studio Code (You can also do this by clicking on the VSCode button right in your repo page. You will have to authorize VSCode to use your GH account to install a GitHub Classroom plugin.)
  2. Click the Explorer tab on the left. You will see a button that says “Clone Repository” (hopefully).
  3. Follow the prompts for authorizing VSCode to use your GH account.
  4. You should see a bar at the top that says “Provide repository URL or pick a repository source.”
  5. Go back to your repository page for your repository and click the green button that says “Code.”
  6. Copy the repo link.
  7. Paste the link into the repository bar and press enter.
  8. It will prompt you for a location to clone the repo into.
  9. Once it is cloned, VSCode will ask if you want to open the cloned repository. Open it.
  10. You should now see the contents of your repository in VSCode.

BASH

$ cd Documents
$ mkdir comp426
$ cd comp426
$ git clone https://github.com/jdmar3-comp426/`a00-$YOURGITHUBUSERNAME`.git
Cloning into 'a00-johnmar3'...
remote: Enumerating objects: 12, done.
remote: Counting objects: 100% (12/12), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 12 (delta 2), reused 2 (delta 0), pack-reused 0
Receiving objects: 100% (12/12), 14.37 KiB | 7.19 MiB/s, done.
Resolving deltas: 100% (2/2), done.
$ cd a00-$YOURGITHUBUSERNAME
$ ls

Et voila! You are in the directory containing your repository! You should be able to see the base files in the repository after your ls command. Now you can open in it whatever editor you wish.

Create a demo project

After completing the last section, your computer should be set up for developing websites in COMP 426! Let’s run through a quick demo to make sure everything works.

For this demo, we’re going to pretend we’re starting a new web dev project. We’ll set up a new project directory using npm and Visual Studio Code. Pay close attention to this process, because you’ll want to repeat it every time you start working on a new COMP 426 assignment that does not already have a packages.json file in it. In fact, this process can even be used outside of class in the real world to get set up working on new web-based projects.

Create a project directory and initialize with npm

The first step for starting a new project is usually to create a new folder that will store your project code. However, for this assignment and for others, you will already have a directory created when you clone your assignment repo. You can see these folders in the left side panel of Visual Studio Code, which shows the file explorer.

The file explorer can be toggled open or closed by clicking on the pictured icon.

The explorer icon in Visual Studio Code

If you were going to be creating a new project folder, you could do it by right clicking in the empty space at the bottom of the explorer and clicking “New Folder.” However, for this demo we will just use the existing folder a00-$YOURGITHUBUSERNAME.

Next, right click on the folder a00-$YOURGITHUBUSERNAME and click “Open in Terminal.” This will open a new terminal window pointing at the a00-$YOURGITHUBUSERNAME folder. This raises an important fact about terminals—they always point to a specific folder location in your computer. Usually, the terminal prompt will give some indication of which folder it is currently pointing at. For instance, you might see something like this:

1
your-computer-name:`a00-$YOURGITHUBUSERNAME` yourname$ 

The important thing here is a00-$YOURGITHUBUSERNAME, which indicates that you are currently in the a00-$YOURGITHUBUSERNAME folder.

There is a special terminal command, pwd, which tells you exactly which folder the terminal is currently in. pwd stands for “print working directory.” Try running pwd in your terminal window now, and verify that it is pointing to the a00-$YOURGITHUBUSERNAME folder.

1
2
$ pwd
/home/YOURUSERNAME/Documents/comp426/`a00-$YOURGITHUBUSERNAME`

Whenever you are working on a particular assignment, it is absolutely crucial that you run any related terminal commands from inside the assignment’s folder.

Once you have confirmed that your terminal is pointing to the a00 folder, run the command npm init. This command tells npm to create a brand new web project in the current folder. As part of the initialization process, it’ll ask you a long list of questions about your new web project. It’s okay to just press enter through all the prompts.

1
$ npm init

What does running npm init actually do? It’s actually pretty simple: it just creates a new package.json file in the current directory. The package.json file is npm’s version of a configuration file for your entire web project. It includes lots of valuable information about your project including the project’s name, version, description, and author. It also includes a list of the dependencies that your project relies on, and a list of custom scripts, or actions, that may be a part of your web application. The answers you type to the questions asked during the npm init process are used to add more information to the package.json file that is created for your project.

At this point, the a00-$YOURGITHUBUSERNAME folder should now have a brand new package.json file with the following contents:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "name": "a00",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Add some HTML

Next, let’s add some html. Right click on the a00-$YOURGITHUBUSERNAME folder, select “New File,” and name the new file index.html.

Write (do not copy and paste) the following code into the new file and save:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<!DOCTYPE html>
<html lang="en">
    <head>  
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Alphabet</title>
    </head>
    <body>
        <div>
            <h1>Alphabet table</h1>
            <table>
				<thead>
  					<tr>
    					<th>Column 0</th><th>Column 1</th>
  					</tr>
				</thead>
				<tbody>
  					<tr>
    					<td>A</td><td></td>
  					</tr>
  					<tr>
    					<td></td><td>B</td>
  					</tr>
  					<tr>
    					<td></td><td>C</td>
  					</tr>
  					<tr>
    					<td></td><td>D</td>
  					</tr>
  					<tr>
    					<td>E</td><td></td>
  					</tr>
  					<tr>
    					<td>F</td><td></td>
  					</tr>
  					<tr>
    					<td></td><td>G</td>
  					</tr>
  					<tr>
    					<td>?</td><td>?</td>
  					</tr>
				</tbody>
			</table>
        </div>
    </body>
</html>

Commit changes

You have just added a file. Save it and then look at the tabs on the left. You should see one that has a blue dot with a number: it is the source control tab. This means that you have changes you need to commit.

The source control icon in Visual Studio Code

You can review the changes and explore the tree, etc. For now, click the check mark, which will trigger a commit. A bar will appear at the top asking you to write a commit message. Write something meaningful to let your future self know what you did: “added index.html”.

To make a commit in your terminal from inside the a00-$YOURGITHUBUSERNAME directory, run the following:

$ git add -v . 
$ git commit -a -m "added index.html"

The first command adds any new files that you created. The second command commits the changes and leaves a log message. Make commits anytime you add or edit files after you have tested them to make sure they are working properly. To test them, keep following these instructions.

Install Browsersync

Next, we’re going to use npm to add our first dependency to the new a00 web project. The package we’ll add is called Browsersync, and it will help make web development much easier! Browsersync is a “dev server,” and its job is to show you what your website looks like in real time as you actively make changes to your code. Browsersync works by pretending to be a real web server, running in the background on your computer and monitoring changes to the files in your project directory. Although it’s optional, you may wish to install and use Browsersync when working on all assignments for COMP 426.

To install Browsersync as a dependency for a00-$YOURGITHUBUSERNAME, run the following command inside the a00-$YOURGITHUBUSERNAME terminal:

1
$ npm install browser-sync

Remember back in Section 2.2 when we ran npm install to install dependencies for the COMP 426 code? This time we’re adding the extra word (called a command line argument) browser-sync to the command. This tells npm to search online for the package named browser-sync, add it as a dependency to our new project a00, and download it. One simple command automatically added a powerful third-party program to your new app—without even writing a single line of code! We’ll be using npm install a lot this semester to add other third-party packages to our code.

Note: To get credit for a00, you must have Browsersync added as a dependency to your project.

Start the development server

With the simple index.html file in place, its time to see if things actually work. Using the terminal inside the a00-$YOURGITHUBUSERNAME folder, run the following command to start the development server:

1
$ npx browser-sync start -sw

A browser window should have been automatically opened, showing the HTML page we created in the prior step. If not, open http://localhost:3000/ in Google Chrome. You should see the text inside the <h1> </h1> and <p> </p> now being rendered on the website.

Note: The command npx browser-sync start -sw is worth memorizing, especially if you plan to use Browsersync for assignments in COMP 426 (which is highly recommended). Browsersync is actually quite a powerful tool, although we won’t get into the more advanced features. If you’re interested in learning more, here’s a list of the supported command line options. The -sw part of the command tells Browsersync to serve your files locally and actively watch for changes that you may be making to the code. Because we didn’t install the browser-sync globally we need to use the npx command to run it locally.

Edit Some HTML

The beauty of using a local web server as you develop is that every time you save your changes, the updated version of the website will be immediately shown in the browser window.

To demonstrate this, we’re about to make a change to the index.html file created earlier. The instant you save the changes you make, you should see the webpage automatically reload to reflect the change. This makes development much easier and faster. Get used to this workflow because it is a standard method for viewing changes as you are making them and it will make the rest of your assignments MUCH easier!

Open your index.html file and find the last row of the table that you created earlier. It should look like this:

1
2
3
<tr>
	<td>?</td><td>?</td>
</tr>

Now look at the table in browser sync.

You will see that some of the letters of the alphabet are in Column 0 and others are in Column 1.

I want you to complete the table, by adding a new row for each remaining letter of the alphabet.

Place the remaining letters for subsequent rows in either Column 0 OR Column 1, BUT NOT both. You can place them into columns in whatever way makes some kind of sense to you. Just make sure that there is one letter and one blank cell per row.

As you go, save the changes you are making, and watch the webpage instantly reload in the browser and add new rows to your table!

  • If you’re on Windows, save by pressing Ctrl + S on your keyboard.
  • If you’re on a Mac, save by pressing Cmd + S.

Stop the development server

You may have noticed that back in Visual Studio Code, the terminal panel still looks something like this:

browser-sync is running in Visual Studio Code&quot;

There’s no dollar-sign prompt ($), and the terminal won’t let you type text into it. This is because Browsersync is still running and is using up that whole terminal. If you ever needed access to a second terminal while Browsersync was running, you could always start up another one with View -> Terminal.

Visual Studio Code understands that you may need to use multiple terminals at once, and it provides an easy way to switch between them: the small drop-down to the right of the word “TERMINAL” in the screenshot above. Clicking that drop-down displays a list of all the active terminals running in Visual Studio Code. You can kill, or delete, a terminal with the trash can icon. This immediately terminates whatever process is running in the terminal and shuts that terminal down. Other terminals in Visual Studio Code will be unaffected by this action.

Whenever you finish working, you may wish to stop the Browsersync development server. One way to do this is by clicking the trash can icon, thereby killing the whole terminal window. Another way is to click back on the terminal that has Browsersync running (see screenshot above) and press the Ctrl + C keys on your keyboard. This should exit Browsersync and return the terminal back to a dollar-sign prompt ($).

Pressing the Ctrl + C keys while working in a terminal sends a special interrupt (SIGTSTP or “terminal stop”) to the process currently running on that terminal. That interrupt forces the process to close.

Submit the assignment

If you’ve made it to this point, you’ve finished a00. The final step is to push the code you created.

All assignments in COMP 426 will be submitted by pushing code back to the repository you cloned.

Push your code

  1. In VSCode, go to the source control tab that you used before.
  2. Make sure that all of the changes are committed.
  3. Click the little three dot menu a few items away from the check mark.
  4. Select “Push” from the dropdown menu.

THAT’S IT! YOU’RE DONE WITH THE FIRST ASSIGNMENT!

The autograder will do its thing and you should be able to see if your code meets all the requirements by clicking on the Actions tab in your GH repo after you have pushed. The autograder can take a minute or two, so be patient.

If your code doesn’t pass one of the tests, try to figure out why it didn’t pass, fix the error, commit, and push.

You can commit and push changes as many times as you need to pass all the tests. This goes for every assignment, not just this one. You always have the option of pushing new changes to autograded assignment repos.

A note about HTML validation

If you copied and pasted the HTML from the above block into index.html, then it will not parse as valid because there are intentional whitespace errors in the example block that you probably missed. It is good practice to run your HTML through a validator. Get into the habit of doing this and learning how to read the output so that you can deal with errors. Familiarize yourself with the W3C validator: https://validator.w3.org, which you can use to validate the HTML for this assignment.