221 lines
17 KiB
HTML
221 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="generator" content="pandoc">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
|
|
<title>CTH-2016 / Assignments Configuration</title>
|
|
<style type="text/css">code{white-space: pre;}</style>
|
|
<!--[if lt IE 9]>
|
|
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
<style type="text/css">
|
|
div.sourceCode { overflow-x: auto; }
|
|
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
|
|
margin: 0; padding: 0; vertical-align: baseline; border: none; }
|
|
table.sourceCode { width: 100%; line-height: 100%; }
|
|
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
|
|
td.sourceCode { padding-left: 5px; }
|
|
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
|
code > span.dt { color: #902000; } /* DataType */
|
|
code > span.dv { color: #40a070; } /* DecVal */
|
|
code > span.bn { color: #40a070; } /* BaseN */
|
|
code > span.fl { color: #40a070; } /* Float */
|
|
code > span.ch { color: #4070a0; } /* Char */
|
|
code > span.st { color: #4070a0; } /* String */
|
|
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
|
code > span.ot { color: #007020; } /* Other */
|
|
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
|
code > span.fu { color: #06287e; } /* Function */
|
|
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
|
|
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
|
code > span.cn { color: #880000; } /* Constant */
|
|
code > span.sc { color: #4070a0; } /* SpecialChar */
|
|
code > span.vs { color: #4070a0; } /* VerbatimString */
|
|
code > span.ss { color: #bb6688; } /* SpecialString */
|
|
code > span.im { } /* Import */
|
|
code > span.va { color: #19177c; } /* Variable */
|
|
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
|
code > span.op { color: #666666; } /* Operator */
|
|
code > span.bu { } /* BuiltIn */
|
|
code > span.ex { } /* Extension */
|
|
code > span.pp { color: #bc7a00; } /* Preprocessor */
|
|
code > span.at { color: #7d9029; } /* Attribute */
|
|
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
|
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
|
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
|
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
|
</style>
|
|
<link rel="stylesheet" href="style/html5.css">
|
|
</head>
|
|
<body>
|
|
<content>
|
|
<header>
|
|
<h1 class="title">CTH-2016 / Assignments Configuration</h1>
|
|
</header>
|
|
<nav id="TOC">
|
|
<ul>
|
|
<li><a href="#initialising-your-assignments-repository">Initialising your assignments repository</a><ul>
|
|
<li><a href="#step-1-create-repository-on-github">Step 1: Create repository on Github</a></li>
|
|
<li><a href="#step-2-clone-the-repository-to-your-own-machine">Step 2: Clone the repository to your own machine</a></li>
|
|
</ul></li>
|
|
<li><a href="#creating-a-new-assignment-node-git">Creating a new assignment (Node + Git)</a><ul>
|
|
<li><a href="#step-1-create-a-new-directory-under-your-assignments-repository">Step 1: Create a new directory under your assignments repository</a></li>
|
|
<li><a href="#step-2-initialise-you-project-with-npm-init">Step 2: Initialise you project with npm init</a></li>
|
|
<li><a href="#step-3-optional-npm-install---save-commander">Step 3 (optional): npm install --save commander</a></li>
|
|
<li><a href="#step-4-create-your-actual-assigment-scripts">Step 4: Create your actual assigment script(s)</a></li>
|
|
<li><a href="#step-5-run-you-script">Step 5: Run you script</a></li>
|
|
<li><a href="#step-6-create-a-readme">Step 6: Create a README</a></li>
|
|
<li><a href="#step-7-add-your-created-files-to-git">Step 7: Add your created files to git</a></li>
|
|
<li><a href="#step-8-commit-your-changes-and-push-to-github">Step 8: Commit your changes and push to Github</a></li>
|
|
</ul></li>
|
|
<li><a href="#updating-your-assignment-as-you-make-progress">Updating your assignment as you make progress</a></li>
|
|
<li><a href="#external-resources">External Resources</a></li>
|
|
</ul>
|
|
</nav>
|
|
<h2 id="initialising-your-assignments-repository">Initialising your assignments repository</h2>
|
|
<p>What follows is a recipe to initialise a git repository for your class assignments.</p>
|
|
<h3 id="step-1-create-repository-on-github">Step 1: Create repository on Github</h3>
|
|
<p>First create a repository under your github account. To do so, login to <a href="https://github.com">Github</a> and on the top/right corner of the page select the '+' symbol and 'New repository'</p>
|
|
<p><img src="./img/github-new-repo.png" width='250px' class='inline-img'/></p>
|
|
<p>Then fill in the information for the assignments repo.</p>
|
|
<ul>
|
|
<li>Note 1: Select "Initialize this repository with a README"</li>
|
|
<li>Note 2: From the "Add .gitignore" drop down menu, selecte Node</li>
|
|
</ul>
|
|
<p><img src="./img/github-new-repo-name.png" class='inline-img'/></p>
|
|
<h3 id="step-2-clone-the-repository-to-your-own-machine">Step 2: Clone the repository to your own machine</h3>
|
|
<p>Now that you have a github repo, you need to <code>clone</code> it to your machine. Open a terminal and navigate (<code>cd</code> and <code>ls</code>) to a prefered directory on your machine where you want your assignments to reside (for instance the Desktop).</p>
|
|
<p>When this is done, select the "Clone or download" menu on your githib repo's page and copy the listed url:</p>
|
|
<p><img src="./img/github-new-repo-clone.png" class='inline-img'/></p>
|
|
<p>Coming back to your terminal, simply type the following to <code>clone</code> the repo on your machine:</p>
|
|
<pre><code>$ git clone your-github-repo-url</code></pre>
|
|
<p>(where your-github-repo-url is your copied/pasted url from github)</p>
|
|
<p>This will create a directory under the current folder where your terminal is. To view the changes, simply type:</p>
|
|
<pre><code>$ ls -al</code></pre>
|
|
<hr />
|
|
<h2 id="creating-a-new-assignment-node-git">Creating a new assignment (Node + Git)</h2>
|
|
<p>What follows is a recipe to create a new assignment in your newly initialised git assignments repository.</p>
|
|
<h3 id="step-1-create-a-new-directory-under-your-assignments-repository">Step 1: Create a new directory under your assignments repository</h3>
|
|
<p>If you have followed the previous section, you should now have a repositroy on your machine which is linked to your github account. Let's assume that your repo is named <code>cth2016-assignments/</code> and resides on your Desktop.</p>
|
|
<p>To create a new assigment, you need to point your terminal to the repo:</p>
|
|
<pre><code>$ cd ~/Desktop/cth2016-assignments/</code></pre>
|
|
<p>and then create a new directory, which I will call <code>assignment-x</code>. To do so, on the terminal, simply type:</p>
|
|
<pre><code>$ mkdir assignment-x
|
|
$ cd assignment-x </code></pre>
|
|
<p>This will create a new direcory <code>assignment-x</code> under <code>~/Desktop/cth2016-assignments/</code>. The <code>cd</code> command puts your terminal inside this newly created directory so that you can initialise your actual project in step 2.</p>
|
|
<h3 id="step-2-initialise-you-project-with-npm-init">Step 2: Initialise you project with npm init</h3>
|
|
<p>Node has a package manager named <code>npm</code> (n-ode, p-ackage, m-anager) that automates the task of creating a project from scratch and configures it in a way that is compatible with other node projects. We will use <code>npm</code> during the module.</p>
|
|
<p>To initialise your new assignment under <code>assignment-x</code>, simply emit the follow command:</p>
|
|
<pre><code>$ npm init</code></pre>
|
|
<p>With this commad you will be asked various questions regarding your project's name, version, description, entry point, author, etc. which you can configure at will (press <'enter'> to select and move to the next configuration step).</p>
|
|
<p>A <code>package.json</code> file is created upon the completion of <code>npm init</code>. This file contains all the configurations you selected and can be edited manually.</p>
|
|
<h3 id="step-3-optional-npm-install---save-commander">Step 3 (optional): npm install --save commander</h3>
|
|
<p>This step is optional, yet recommended for your assignment. When making a node application, modules/libraries can be made part of your project using <code>npm</code>. Thousands of javascript libraries are available on <a href="https://www.npmjs.com">www.npmjs.com</a> which you can install with a simple <code>npm</code> command.</p>
|
|
<p>As in the first session of the class on the Command Line Interface (CLI), we will be using <a href="https://www.npmjs.com/package/commander">"commander"</a> for our applications. To install it for you assignment, use the following command:</p>
|
|
<pre><code>$ npm install --save commander</code></pre>
|
|
<p>This will create a <code>node_modules</code> directory next to <code>package.json</code> where the commander code is placed. All modules installed using <code>npm</code> will reside in this <code>node_modules</code> directory.</p>
|
|
<h3 id="step-4-create-your-actual-assigment-scripts">Step 4: Create your actual assigment script(s)</h3>
|
|
<p>Now that you have an npm project created and installed commander it is time to create your script(s). For instance, in this example, I will create <code>index.js</code> file containing the code for the fake assignment. This file can be called anything (for instance, person.js as in the example in class during week1).</p>
|
|
<p>Though since I am not following a proper assignment per se, I will simply create a simple tri-lingual script that will output <code>"Hello!"</code>, <code>"Dag!"</code> or <code>"Allô!"</code> depending on a command line arguments passed to the script which can be of the type <code>en</code> (english), <code>nl</code> (nederlands), <code>fr</code> (français) or nothing.</p>
|
|
<p>To create <code>index.js</code> simply type (or, alternatively, create it with Sublime Text):</p>
|
|
<pre><code>$ touch index.js</code></pre>
|
|
<p>Now open the file usign Sublime Text, copy/paste or input the desired code and save:</p>
|
|
<div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">
|
|
<span class="co">// simplest tri-lingual program </span>
|
|
|
|
<span class="kw">var</span> program <span class="op">=</span> <span class="at">require</span>(<span class="st">'commander'</span>)<span class="op">;</span>
|
|
|
|
program
|
|
.<span class="at">version</span>(<span class="st">'0.1'</span>)
|
|
.<span class="at">option</span>(<span class="st">'-l, --language [code]'</span><span class="op">,</span> <span class="st">'Language'</span><span class="op">,</span> <span class="ss">/</span><span class="sc">^(</span><span class="ss">en</span><span class="sc">|</span><span class="ss">nl</span><span class="sc">|</span><span class="ss">fr</span><span class="sc">)$</span><span class="ss">/i</span>)
|
|
.<span class="at">parse</span>(<span class="va">process</span>.<span class="at">argv</span>)<span class="op">;</span>
|
|
|
|
<span class="cf">switch</span>(<span class="va">program</span>.<span class="at">language</span>)
|
|
<span class="op">{</span>
|
|
<span class="cf">case</span>(<span class="st">'en'</span>)<span class="op">:</span>
|
|
<span class="va">console</span>.<span class="at">log</span>(<span class="st">'Hello!'</span>)<span class="op">;</span>
|
|
<span class="cf">break</span><span class="op">;</span>
|
|
<span class="cf">case</span>(<span class="st">'nl'</span>)<span class="op">:</span>
|
|
<span class="va">console</span>.<span class="at">log</span>(<span class="st">'Dag!'</span>)<span class="op">;</span>
|
|
<span class="cf">break</span><span class="op">;</span>
|
|
<span class="cf">case</span>(<span class="st">'fr'</span>)<span class="op">:</span>
|
|
<span class="va">console</span>.<span class="at">log</span>(<span class="st">'Allô!'</span>)<span class="op">;</span>
|
|
<span class="cf">break</span><span class="op">;</span>
|
|
<span class="dt">default</span><span class="op">:</span>
|
|
<span class="va">console</span>.<span class="at">log</span>(<span class="st">'...'</span>)<span class="op">;</span>
|
|
<span class="cf">break</span><span class="op">;</span>
|
|
<span class="op">}</span></code></pre></div>
|
|
<h3 id="step-5-run-you-script">Step 5: Run you script</h3>
|
|
<p>To run the script</p>
|
|
<pre><code>$ node index.js -l fr
|
|
Allô!</code></pre>
|
|
<p>where you can replace <code>fr</code> by <code>en</code> or <code>nl</code> or nothing. Try it out!</p>
|
|
<p>If you called you script another name (for instance, person.js), please change the above <code>index.js</code> with the name of your own script.</p>
|
|
<h3 id="step-6-create-a-readme">Step 6: Create a README</h3>
|
|
<p>One of the interesting feature of commander is that it can auto generate a <code>"help"</code> output from your script based on the command line options you have listed in your program.</p>
|
|
<p>To see this help output, simply type:</p>
|
|
<pre><code>$ node index.js --help</code></pre>
|
|
<pre><code> Usage: index [options]
|
|
|
|
Options:
|
|
|
|
-h, --help output usage information
|
|
-V, --version output the version number
|
|
-l, --language [code] Language
|
|
</code></pre>
|
|
<p>It is very common for command line scripts to feature such <code>--help</code> argument that when executed, displays what the program expects as input. Thus, for this class, each README you will create (for both assignments and final project) is expected to have (at least) this type of "helper documentation".</p>
|
|
<p>To initialise a README and add the <code>help</code> output from your script:</p>
|
|
<pre><code>$ node index.js --help > README</code></pre>
|
|
<p>Alternatively, you can create the README with Sublime Text and copy/paste the result of the <code>--help</code> manually.</p>
|
|
<p>It is a very good practice to start the redaction with the <code>--help</code> as it signals how to use your script to people that may be interested in it.</p>
|
|
<h3 id="step-7-add-your-created-files-to-git">Step 7: Add your created files to git</h3>
|
|
<p>Now that you have a proper project initialised, the next step is to add all its files to git.</p>
|
|
<p>To view which file needs to be added to git type:</p>
|
|
<pre><code>$ git status</code></pre>
|
|
<p>This should indicate which directories and/or files are untracked by git.</p>
|
|
<p>If you have followed the previous steps, <code>git status</code> should simply signal that the current directory <code>./</code> is untracked. To add it to git:</p>
|
|
<pre><code>$ git add ./</code></pre>
|
|
<p>To make sure git properly added the new assignment, simply type (again):</p>
|
|
<pre><code>$ git status</code></pre>
|
|
<p>and check that your <code>package.json</code>, <code>index.js</code> (or whatever you have called your file(s)), and <code>README</code> are marked as new files (green).</p>
|
|
<h3 id="step-8-commit-your-changes-and-push-to-github">Step 8: Commit your changes and push to Github</h3>
|
|
<p>The next step is to commit these new files to your local git repo:</p>
|
|
<pre><code>$ git commit -a -m "initial commit for assignment-x"</code></pre>
|
|
<p>And push the commit to your assignments github repo:</p>
|
|
<pre><code>$ git push origin master</code></pre>
|
|
<p>You should now see these changes online in your new <code>cth2016-assignments/assignment-x/</code> directory:</p>
|
|
<p><img src="./img/github-assignment-x.png" class='inline-img'/></p>
|
|
<p>NOTE: <code>node_modules</code> is not be pushed to github, why? Because when someone will clone your project (your instructor for example), she/he will <code>npm install</code> it her/himself as it is listed as a dependency in <code>package.json</code>.</p>
|
|
<hr />
|
|
<h2 id="updating-your-assignment-as-you-make-progress">Updating your assignment as you make progress</h2>
|
|
<p>It is assumed that you will make many changes to your assigment while your a working on it.</p>
|
|
<p>The ususall cycle of working on some piece of code is to first (1) add you files to the repo (re: Step 7), (2) modify your files while you are working, and (3) when your code is working as inteted, commit your changes and push to github (re: Step 8).</p>
|
|
<p>The usual updating loop looks a bit like this:</p>
|
|
<ol style="list-style-type: decimal">
|
|
<li><code>git status</code></li>
|
|
<li>(optional) <code>git add</code> xyz depending on what was added to the project while working on it.</li>
|
|
<li><code>git commit -a -m "message for the commit"</code></li>
|
|
<li><code>git push origin master</code></li>
|
|
<li>work a bit more</li>
|
|
<li>loop and goto 1.</li>
|
|
</ol>
|
|
<h2 id="external-resources">External Resources</h2>
|
|
<p>Github</p>
|
|
<ul>
|
|
<li><a href="https://help.github.com/articles/set-up-git/">Github Help - Set Up Git</a></li>
|
|
<li><a href="https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/">Github Help - Adding an existing project</a></li>
|
|
</ul>
|
|
<p>Git</p>
|
|
<ul>
|
|
<li><a href="https://git-scm.com/book/en/v1/Getting-Started">Git - Getting Started</a></li>
|
|
<li><a href="https://git-scm.com/videos">Git - Getting Started (Videos)</a></li>
|
|
<li><a href="http://swcarpentry.github.io/git-novice/">Software Carpentry - Git Tutorial</a></li>
|
|
</ul>
|
|
<p>Node</p>
|
|
<ul>
|
|
<li><a href="https://nodeschool.io/#workshopper-list">Nodeschool</a></li>
|
|
</ul>
|
|
</content>
|
|
</body>
|
|
</html> |