# E01: lab0

:::info
主講人: [jserv](http://wiki.csie.ncku.edu.tw/User/jserv) / 課程討論區: [2018 年系統軟體課程](https://www.facebook.com/groups/system.software2018/)
:mega: 返回「[進階電腦系統理論與實作](http://wiki.csie.ncku.edu.tw/sysprog/schedule)」課程進度表
:::

## 預期目標

* 英文閱讀
* C 語言程式設計基礎
* 準備 GNU/Linux 開發工具
* 學習使用 Git 與 GitHub
* 學習效能分析
* 研究自動測試機制

## Introduction to Computer Systems (ICS) 的第一份作業

CMU [Introduction to Computer Systems (ICS)](http://www.cs.cmu.edu/~213/index.html) 準備了 [C Programming Lab](http://www.cs.cmu.edu/~213/labs/cprogramminglab.pdf) 作為檢閱學生 C 語言程式設計的認知:
* Explicit memory management, as required in C.
* Creating and manipulating pointer-based data structures.
* Working with strings.
* Enhancing the performance of key operations by storing redundant information in data structures.
* Implementing robust code that operates correctly with invalid arguments, including NULL pointers.

實驗目標為實作 queue
* first in, first out (FIFO)
* last in, first out (LIFO)

## 使用 clang-format + [Git Hooks](https://www.atlassian.com/git/tutorials/git-hooks) 進行自動程式碼排版檢查

* 使用一致的 coding style 很重要，我們可透過 [clang-format](https://clang.llvm.org/docs/ClangFormat.html) 這個工具來調整作業程式要求的風格為以下:

    $ clang-format -i *.[ch]

* 你可以想像 Apple 和 Google 的工程師隨便安置程式碼，然後不用管合作的議題嗎？
* 即便一個人寫作業，其實是三人的參與：過去的你、現在的你，以及未來的你
* 當首次執行 `make` 後，Git pre-commit hook 將自動安裝到現行的工作區 (workspace)，之後每次執行 `git commit` 時，Git hook 會檢查 C/C++ 原始程式碼的風格是否一致:
* 我們介紹 [Git hooks](https://goo.gl/CNMHZJ) 是為了日後銜接 Continuous integration (CI)，專業程式設計必備的準備工作
* 任何人都可以寫出機器看得懂的程式碼 (在檔案總管裡面對 EXE 檔複製貼上即可)，但我們之所以到資訊工程系接受訓練，為了寫出人看得懂、可持續維護和改進的程式
* 下圖展示 Git pre-commit hook 偵測到開發者的修改並未遵守一致的 coding style，主動回報並提醒開發者:

## 自動評分系統

`qtest` 執行檔內有包裝許多測試這次作業可用的工具，執行 `qtest` 後可打 `help` 即有各指令解說

make
./qtest
cmd>help
Commands:
        #        ...            | Display comment
        free                    | Delete queue
        help                    | Show documentation
        ih       v [n]          | Insert v at head of queue n times (default: n == 1)
        it       v [n]          | Insert v at tail of queue n times (default: n == 1)
        log      file           | Copy output to file
        new                     | Create new queue
        option   [name val]     | Display or set options
        quit                    | Exit program
        reverse                 | Reverse queue
        rh       [v]            | Remove from head of queue.  Optionally compare to expected value v
        rhq      [v]            | Remove from head of queue without reporting value
        show                    | Show queue contents
        size     [n]            | Compute queue size n times (default: n == 1)
        source   file           | Read commands from source file
        time     cmd arg ...    | Time command execution
Options:
        echo    1       Do/don't echo commands
        error   5       Number of errors until exit
        fail    30      Number of times allow queue operations to return false
        malloc  0       Malloc failure probability percent
        verbose 4       Verbosity level

qtest 使用範例:

# 確認目前 queue 內容（一開始應該是空的 q = NULL）
show
# 新建一個 queue (q = [])
new
# 在 head 新增數值
ih 2
ih 1
ih 3
# 結果：
#q = []
#cmd>ih 1
#cmd>ih 1
#q = [1]
#cmd>ih 2
#cmd>ih 2
#q = [2 1]
#cmd>ih 3
#cmd>ih 3
#q = [3 2 1]
# 現在從尾巴加（應該會失敗因為還沒實作)
it 5
4
it 1
# 反轉 queue, 算長度, 釋放記憶體等..（應該都會失敗因為還沒實作)
reverse
size
free
# 離開
quit

* 計算得分：

make test

如果什麼都沒做，當然是零分，參考輸出:

 Test performance of insert_tail, size, and reverse
ERROR: Need to allocate separate string for each list element
ERROR: Insertion of gerbil failed (1 failures total)
ERROR:  Computed queue size as 0, but correct value is 2
ERROR:  Computed queue size as 0, but correct value is 2
---	trace-15-perf	0/7
---	TOTAL		0/100

## 開發環境設定

1. 依據 [GNU/Linux 開發工具共筆](https://hackmd.io/c/rJKbX1pFZ) 的指引，設定好 git, GitHub 帳號, vim (或其他你偏好的編輯器), perf, gnuplot
2. 安裝以下開發工具

    $ apt install build-essential git-core cppcheck clang-format

## 作業要求

* 在 GitHub 上 fork [lab0-c](https://github.com/sysprog21/lab0-c)
* 參閱 [GitHub 設定指引](http://wiki.csie.ncku.edu.tw/github)
* ==詳細閱讀 [C Programming Lab](http://www.cs.cmu.edu/~213/labs/cprogramminglab.pdf)== (英文閱讀正是我們想強化的議題)，依據指示著手修改 `queue.[ch]` 和連帶的檔案，測試後用 Git 管理各項修改。
* 在提交程式前，務必詳閱 [如何寫好 Git Commit Message](https://blog.louie.lu/2017/03/21/%E5%A6%82%E4%BD%95%E5%AF%AB%E4%B8%80%E5%80%8B-git-commit-message/)
* 不用理會 [Autolab](http://www.autolabproject.com/) 和檔案下載的描述，這兩者都是 CMU 專屬
* 除了修改程式，也要編輯「[作業區](https://hackmd.io/s/rJwiDHGKQ)」，增添開發紀錄和 GitHub 連結，提及如何逐步達到要求，以及如何改善效能
* 解釋自動評分系統運作的原理
* 提及 `qtest` 的行為和裡頭的技巧
* 截止日期：
* Oct 7, 2018 (含) 之前
* 越早在 GitHub 上有動態、越早接受 code review，評分越高