---
title: 章 2. 程式開發工具
authors:
  - author: James Raynard
  - author: Murray Stokelyç
prev: books/developers-handbook/introduction
next: books/developers-handbook/secure
---

[[tools]]
= 程式開發工具
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:toc-title: 目录
:part-signifier: 部分
:chapter-signifier: 第
:appendix-caption: 附录
:table-caption: 表
:figure-caption: 图
:example-caption: 例 
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:c-plus-plus-command: c++
:g-plus-plus-command: g++
:lg-plus-plus: -lg++
:lstdc-plus-plus: -lstdc++
:sectnumoffset: 2

include::shared/mirrors.adoc[]
include::shared/authors.adoc[]
include::shared/releases.adoc[]
include::shared/zh-tw/mailing-lists.adoc[]
include::shared/zh-tw/urls.adoc[]

toc::[]

[[tools-synopsis]]
== 概敘

本章將介紹如何使用一些 FreeBSD 所提供的程式開發工具(programing tools)， 本章所介紹的工具程式在其他版本的 上也可使用， 在此 _並不會_ 嘗試描述寫程式時的每個細節， 本章大部分篇幅都是假設你以前沒有或只有少數的寫程式經驗， 不過，還是希望大多數的程式開發人員都能從中重新得到一些啟發。

[[tools-intro]]
== 簡介

FreeBSD 提供一個非常棒的開發環境， 比如說像是 C、C++、Fortran 和 assembler(組合語言)的編譯器(compiler), 在 FreeBSD 中都已經包含在基本的系統中了 更別提 Perl 和其他標準 工具，像是``sed`` 以及 `awk`， 如果你還是覺得不夠，FreeBSD在 Ports collection 中還提供其他的編譯器和直譯器(interpreter), FreeBSD 相容許多標準，像是  和 ANSI C， 當然還有它所繼承的 BSD 傳統。 所以在 FreeBSD 上寫的程式不需修改或頂多稍微修改，就可以在許多平台上編譯、執行。

無論如何，就算你從來沒在 平台上寫過程式，也可以徹底感受到FreeBSD 令人無法抗拒的迷人魔力。 本章的目標就是協助你快速上手，而暫時不需深入太多進階主題， 並且講解一些基礎概念，以讓你可以瞭解我們在講些什麼。

本章內容並不要求你得有程式開發經驗，或者你只有一點點的經驗而已。 不過，我們假設你已經會 系統的基本操作， 而且更重要的是，請保持樂於學習的心態！

[[tools-programming]]
== Programming 概念

簡單的說，程式只是一堆指令的集合體；而這些指令是用來告訴電腦應該要作那些事情。 有時候，指令的執行取決於前一個指令的結果而定。 本章將會告訴你有 2 個主要的方法，讓你可以對電腦下達這些指示(instruction) 或 "命令(commands)"。 第一個方法就是 _直譯器(interpreter)_， 而第二個方法是 _編譯器(compiler)_。 由於對於電腦而言，人類語言的語意過於模糊而太難理解， 因此命令(commands)就常會以一種(或多種)程式語言寫成，用來指示電腦所要執行的特定動作為何。

=== 直譯器

使用直譯器時，所使用的程式語言就像變成一個會和你互動的環境。 當在命令提示列上打上命令時，直譯器會即時執行該命令。 在比較複雜的程式中，可以把所有想下達的命令統統輸入到某檔案裡面去， 然後呼叫直譯器去讀取該檔案，並且執行你寫在這個檔案中的指令。 如果所下的指令有錯誤產生，大多數的直譯器會進入偵錯模式(debugger)， 並且顯示相關錯誤訊息，以便對程式除錯。

這種方式好處在於：可以立刻看到指令的執行結果，以及錯誤也可迅速修正。 相對的，最大的壞處便是當你想把你寫的程式分享給其他人時，這些人必須要有跟你一樣的直譯器。 而且別忘了，他們也要會使用直譯器直譯程式才行。 當然使用者也不希望不小心按錯鍵，就進入偵錯模式而不知所措。 就執行效率而言，直譯器會使用到很多的記憶體， 而且這類直譯式程式，通常並不會比編譯器所編譯的程式的更有效率。

筆者個人認為，如果你之前沒有學過任何程式語言，最好先學學習直譯式語言(interpreted languages)， 像是 Lisp，Smalltalk，Perl 和 Basic 都是， 的 shell 像是 `sh` 和 `csh` 它們本身就是直譯器，事實上，很多人都在它們自己機器上撰寫各式的 shell "script"， 來順利完成各項 "housekeeping(維護)" 任務。 的使用哲學之一就是提供大量的小工具， 並使用 shell script 來組合運用這些小工具，以便工作更有效率。

=== FreeBSD 提供的直譯器

下面這邊有份 Ports Collection 所提供的直譯器清單，還有討論一些比較受歡迎的直譯式語言

至於如何使用 Ports Collection 安裝的說明，可參閱 FreeBSD Handbook 中的 link:{handbook}ports-using[Ports章節]。

BASIC::
BASIC 是 Beginner's ALL-purpose Symbolic Instruction Code 的縮寫。 BASIC 於 1950 年代開始發展，最初開發這套語言的目的是為了教導當時的大學學生如何寫程式。 到了 1980，BASIC已經是很多 programmer 第一個學習的程式語言了。 此外，BASIC 也是 Visual Basic 的基礎。
+
FreeBSD Ports Collection 也有收錄相關的 BASIC 直譯器。 Bywater Basic 直譯器放在 package:lang/bwbasic[]。 而 Phil Cockroft's Basic 直譯器(早期也叫 Rabbit Basic)放在 package:lang/pbasic[]。

Lisp::
LISP 是在 1950 年代開始發展的一個直譯式語言，而且 LISP 就是一種 "number-crunching" languages(迅速進行大量運算的程式語言)，在當時算是一個普遍的程式語言。 LISP 的表達不是基於數字(numbers)，而是基於表(lists)。 而最能表示出 LISP 特色的地方就在於： LISP 是 "List Processing" 的縮寫。 在人工智慧(Artificial Intelligence, AI)領域上 LISP 的各式應用非常普遍。
+
LISP 是非常強悍且複雜的程式語言，但是缺點是程式碼會非常大而且難以操作。
+
絕大部分的 LISP 直譯器都可以在 系統上運作，當然 的 Ports Collection 也有收錄。 GNU Common Lisp 收錄在 package:lang/gcl[]， Bruno Haible 和 Michael Stoll 的 CLISP 收錄在 package:lang/clisp[] ，此外 CMUCL(包含一個已經最佳化的編譯器)， 以及其他簡化版的 LISP 直譯器(比如以 C 語言寫的 SLisp，只用幾百行程式碼就實作大多數 Common Lisp 的功能) 則是分別收錄在 package:lang/cmucl[] 以及 package:lang/slisp[]。

Perl::
對系統管理者而言，最愛用 perl 來撰寫 scripts 以管理主機， 同時也經常用來寫 WWW 主機上的 CGI Script 程式。
+
Perl 在 Ports Collection 內的 package:lang/perl5[]。 而 4.X 則是把 Perl 裝在 `/usr/bin/perl`。

Scheme::
Scheme 是 LISP 的另一分支，Scheme 的特點就是比 Common LISP 還要簡潔有力。 由於 Scheme 簡單，所以很多大學拿來當作第一堂程式語言教學教材。 而且對於研究人員來說也可以快速的開發他們所需要的程式。
+
Scheme 收錄在 package:lang/elk[]， Elk Scheme 直譯器(由麻省理工學院所發展的 Scheme 直譯器)收錄在 package:lang/mit-scheme[]， SCM Scheme Interpreter 收錄在 package:lang/scm[]。

Icon::
Icon 屬高階程式語言，Icon 具有強大的字串(String)和結構(Structure)處理能力。 Ports Collection 所收錄的 Icon 直譯器版本則是放在 package:lang/icon[]。

Logo::
Logo 是種容易學習的程式語言，最常在一些教學課程中被拿來當作開頭範例。 如果要給小朋友開始上程式語言課的話，Logo 是相當不錯的選擇。 因為，即使對小朋友來說，要用 Logo 來秀出複雜多邊形圖形是相當輕鬆容易的。
+
Logo 在 Ports Collection 的最新版則是放在 package:lang/logo[]。

Python::
Python 是物件導向的直譯式語言， Python 的擁護者總是宣稱 Python 是最好入門的程式語言。 雖然 Python 可以很簡單的開始，但是不代表它就會輸給其他直譯式語言(像是 Perl 和 Tcl)， 事實證明 Python 也可以拿來開發大型、複雜的應用程式。
+
Ports Collection 收錄在 package:lang/python[]。

Ruby::
Ruby 是純物件導向的直譯式語言。 Ruby 目前非常流行，原因在於他易懂的程式語法結構，在撰寫程式時的彈性， 以及天生具有輕易的發展維護大型專案的能力。
+
Ports Collection 收錄在 package:lang/ruby8[]。

Tcl and Tk::
Tcl 是內嵌式的直譯式語言，讓 Tcl 可以如此廣泛運用的原因是 Tcl 的移植性。 Tcl 也可以快速發展一個簡單但是具有雛型的程式或者具有完整功能的程式。
+
Tcl 許多的版本都可在 上運作，而最新的 Tcl 版本為 Tcl 8.4， Ports Collection 收錄在 package:lang/tcl84[]。

=== 編譯器

編譯器和直譯器兩者相比的話，有些不同，首先就是必須先把程式碼統統寫入到檔案裡面， 然後必須執行編譯器來試著編譯程式，如果編譯器不接受所寫的程式，那就必須一直修改程式， 直到編譯器接受且把你的程式編譯成執行檔。 此外，也可以在提示命令列，或在除錯器中執行你編譯好的程式看看它是否可以運作。 

很明顯的，使用編譯器並不像直譯器般可以馬上得到結果。 不管如何，編譯器允許你作很多直譯器不可能或者是很難達到的事情。 例如：撰寫和作業系統密切互動的程式，甚至是你自己寫的作業系統！ 當你想要寫出高效率的程式時，編譯器便派上用場了。 編譯器可以在編譯時順便最佳化你的程式，但是直譯器卻不行。 而編譯器與直譯器最大的差別在於：當你想把你寫好的程式拿到另外一台機器上跑時， 你只要將編譯器編譯出來的可執行檔，拿到新機器上便可以執行， 而直譯器則必須要求新機器上，必須要有跟另一台機器上相同的直譯器， 才能組譯執行你的程式！

編譯式的程式語言包含 Pascal、C 和 {c-plus-plus-command}， C 和 {c-plus-plus-command} 不是一個親和力十足的語言，但是很適合具有經驗的 Programmer。 Pascal 其實是一個設計用來教學用的程式語言，而且也很適合用來入門， 預設並沒有把 Pascal 整合進 base system 中， 但是 GNU Pascal Compiler 和 Free Pascal Compiler 都可分別在 package:lang/gpc[] 和 package:lang/fpc[] 中找到。

如果你用不同的程式來寫編譯式程式，那麼不斷地編輯-編譯-執行-除錯的這個循環肯定會很煩人， 為了更簡化、方便程式開發流程，很多商業編譯器廠商開始發展所謂的 IDE (Integrated Development Environments) 開發環境， FreeBSD 預設並沒有把 IDE 整合進 base system 中， 但是你可透過 package:devel/kdevelop[] 安裝 kdevelop 或使用 Emacs 來體驗 IDE 開發環境。 在後面的 <<emacs>> 專題將介紹，如何以 Emacs 來作為 IDE 開發環境。

[[tools-compiling]]
== 用 `cc` 來編譯程式

本章範例只有針對 GNU C compiler 和 GNU C++ compiler 作說明， 這兩個在 FreeBSD base system 中就有了， 直接打 `cc` 或 `gcc` 就可以執行。 至於，如何用直譯器產生程式的說明，通常可在直譯器的文件或線上文件找到說明，因此不再贅述。

當你寫完你的傑作後，接下來便是讓這個程式可以在 FreeBSD 上執行， 通常這些要一些步驟才能完成，有些步驟則需要不同程式來完成。

[.procedure]
====
. 預先處理(Pre-process)你的程式碼，移除程式內的註解，和其他技巧， 像是 expanding(擴大) C 的 marco。
. 確認你的程式語法是否確實遵照 C/C++ 的規定，如果沒有符合的話，編譯器會出現警告。
. 將原始碼轉成組合語言 它跟機器語言(machine code)非常相近，但仍在人類可理解的範圍內(據說應該是這樣)。 
. 把組合語言轉成機器語言 是的，這裡說的機器語言就是常提到的 bit 和 byte，也就是 1 和 0。
. 確認程式中用到的函式呼叫、全域變數是否正確，舉例來說：如若呼叫了不存在的函式，編譯器會顯示警告。
. 如果程式是由程式碼檔案來編譯，編譯器會整合起來。
. 編譯器會負責產生東西，讓系統上的 run-time loader 可以把程式載入記憶體內執行。
. 最後會把編譯完的執行檔存在硬碟上。
====

通常 _編譯(compiling)_ 是指第 1 到第 4 個步驟。 其他步驟則稱為 _連結(linking)_， 有時候步驟 1 也可以是指 _預先處理(pre-processing)_， 而步驟 3 到步驟 4 則是 _組譯(assembling)_。

幸運的是，你可以不用理會以上細節，編譯器都會自動完成。 因為 `cc` 只是是個前端程式(front end)，它會依照正確的參數來呼叫相關程式幫你處理。 只需打：

[source,bash]
....
% cc foobar.c
....

上述指令會把 [.filename]#foobar.c# 開始編譯，並完成上述動作。 如果你有許多檔案需要編譯，那請打類似下列指令即可：

[source,bash]
....
% cc foo.c bar.c
....

記住語法錯誤檢查就是 純粹檢查語法錯誤與否， 而不會幫你檢測任何邏輯錯誤，比如：無限迴圈，或是排序方式想用 binary sort 卻弄成 bubble sort。 

`cc` 有非常多的選項，都可透過線上手冊來查。 下面只提一些必要且重要的選項，以作為例子。

`-o _檔名_`::
`-o` 編譯後的執行檔檔名，如果沒有使用這選項的話， 編譯好的程式預設檔名將會是 [.filename]#a.out#
+
[source,bash]
....
% cc foobar.c               執行檔就是 a.out
% cc -o foobar foobar.c     執行檔就是 foobar
....

`-c`::
使用 `-c` 時，只會編譯原始碼，而不作連結(linking)。 當只想確認語法是否正確或使用 Makefile 來編譯程式時，這個選項非常有用。
+
[source,bash]
....
 % cc -c foobar.c
....
+
這會產生叫做 [.filename]#foobar# 的 _object file_(非執行檔)。 這檔可以與其他的 object file 連結在一起，而成執行檔。

`-g`::
`-g` 將會把一些給 gdb 用的除錯訊息包進去執行檔裡面，所謂的除錯訊息例如： 程式在第幾行出錯、那個程式第幾行做什麼函式呼叫等等。除錯資訊__非常__好用。 但缺點就是：對於程式來說，額外的除錯訊息會讓編譯出來的程式比較肥些。 `-g` 的適用時機在於：當程式還在開發時使用就好， 而當你要釋出你的 "發行版本(release version)" 或者確認程式可運作正常的話，就不必用 `-g` 這選項了。
+
[source,bash]
....
% cc -g foobar.c
....
+
這動作會產生有含除錯訊息的執行檔。 

`-O`::
`-O` 會產生最佳化的執行檔， 編譯器會使用一些技巧，來讓程式可以跑的比未經最佳化的程式還快， 可以在大寫 O 後面加上數字來指明想要的最佳化層級。 但是最佳化還是會有一些錯誤，舉例來說在 FreeBSD 2.10 release 中用 `cc` 且指定 `-O2` 時，在某些情形下會產生錯誤的執行檔。
+
只有當要釋出發行版本、或者加速程式時，才需要使用最佳化選項。
+
[source,bash]
....
% cc -O -o foobar foobar.c
....
+
這會產生 [.filename]#foobar# 執行檔的最佳化版本。

以下三個參數將會強迫 `cc` 確認程式碼是否符合一些國際標準的規範， 也就是通常說的 ANSI 標準， 而 ANSI 嚴格來講屬 ISO 標準。

`-Wall`::
`-Wall` 顯示 `cc` 維護者所認為值得注意的所有警告訊息。 不過這名字可能會造成誤解，事實上它並未完全顯示 `cc` 所能注意到的各項警告訊息。

`-ansi`::
`-ansi` 關閉 `cc` 特有的某些特殊非 ANSI C 標準功能。 不過這名字可能會造成誤解，事實上它並不保證你的程式會完全符合 ANSI 標準。

`-pedantic`::
全面關閉 `cc` 所特有的非 ANSI C 標準功能。

除了這些參數，`cc` 還允許你使用一些額外的參數取代標準參數，有些額外參數非常有用， 但是實際上並不是所有的編譯器都有提供這些參數。 照標準來寫程式的最主要目的就是，希望你寫出來的程式可以在所有編譯器上編譯、執行無誤， 當程式可以達成上述目的時，就稱為 _portable code(移植性良好的程式碼)_。

一般來說，在撰寫程式時就應要注意『移植性』。 否則。當想把程式拿到另外一台機器上跑的時候，就可能得需要重寫程式。

[source,bash]
....
% cc -Wall -ansi -pedantic -o foobar foobar.c
....

上述指令會確認 [.filename]#foobar.c# 內的語法是否符合標準， 並且產生名為 [.filename]#foobar# 的執行檔。

`-l _library_`::
告訴 gcc 在連結(linking)程式時你需要用到的函式庫名稱。
+
最常見的情況就是，當你在程式中使用了 C 數學函式庫， 跟其他作業平台不一樣的是，這函示學函式都不在標準函式庫(library)中， 因此編譯器並不知道這函式庫名稱，你必須告訴編譯器要加上它才行。
+
規則很簡單，如果有個函式庫叫做 [.filename]#libsomething.a#， 就必須在編譯時加上參數 `-l _something_` 才行。 舉例來說，數學函式庫叫做 [.filename]#libm.a#， 所以你必須給 `cc` 的參數就是 `-lm`。 一般情況下，通常會把這參數必須放在指令的最後。
+
[source,bash]
....
% cc -o foobar foobar.c -lm
....
+
上面這指令會讓 gcc 跟數學函式庫作連結，以便你的程式可以呼叫函式庫內含的數學函式。
+
如果你正在編譯的程式是 C++ 程式碼，你還必須額外指定 {lg-plus-plus} 或者是 {lstdc-plus-plus}。 如果你的 FreeBSD 是 2.2(含)以後版本， 你可以用指令 {c-plus-plus-command} 來取代 `cc`。 在 FreeBSD 上 {c-plus-plus-command} 也可以用 {g-plus-plus-command} 取代。
+
[source,bash]
....
% cc -o foobar foobar.cc -lg++     適用 FreeBSD 2.1.6 或更早期的版本
% cc -o foobar foobar.cc -lstdc++  適用 FreeBSD 2.2 及之後的版本
% c++ -o foobar foobar.cc
....
+
上述指令都會從原始檔 [.filename]#foobar.cc# 編譯產生名為 [.filename]#fooboar# 的執行檔。 這邊要提醒的是在 系統中 {c-plus-plus-command} 程式傳統都以 [.filename]#.C#、 [.filename]#.cxx# 或者是 [.filename]#.cc# 作為副檔名， 而非 那種以 [.filename]#.cpp# 作為副檔名的命名方式(不過也越來越普遍了)。 `gcc` 會依副檔名來決定用哪一種編譯器編譯， 然而，現在已經不再限制副檔名了， 所以可以自由的使用 [.filename]#.cpp# 作為 {c-plus-plus-command} 程式碼的副檔名！

=== 常見的 `cc` 問題

==== 我用 sin() 函示撰寫我的程式， 但是有個錯誤訊息(如下)，這代表著？

[source,bash]
....
/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment
....

當使用 `sin()` 這類的數學函示時， 你必須告訴 cc 要和數學函式庫作連結(linking)，就像這樣：

[source,bash]
....
% cc temp.c -lm
....

==== 好吧，我試著寫些簡單的程式，來練習使用 -lm 選項(該程式會運算 2.1 的 6 次方)

當編譯器發現你呼叫一個函示時，它會確認該函示的回傳值類型(prototype)， 如果沒有特別指明，則預設的回傳值類型為 [type]#int(整數)#。 很明顯的，你的程式所需要的並不是回傳值類別為 [type]#int#。

==== 那如何才可以修正剛所說的問題？

數學函示的回傳值類型(prototype)會定義在 [.filename]#math.h#， 如果你有 include 這檔，編譯器就會知道該函示的回傳值類型，如此一來該運算就會得到正確的結果！

[.programlisting]
....
#include <stdio.h>

int main() {
	float f;

	f = pow(2.1, 6);
	printf("2.1 ^ 6 = %f\n", f);
	return 0;
}
....

編譯後執行程式，得到下面這結果：

[source,bash]
....
% cc temp.c -lm
....

加了上述內容之後，再重新編譯，最後執行：

[source,bash]
....
% ./a.out
2.1 ^ 6 = 85.766121
....

如果有用到數學函式，__請確定__要有 include [.filename]#math.h# 這檔， 而且記得要和數學函式庫作連結。

==== 已經編譯好 foobar.c， 但是編譯後找不到 foobar 執行檔。 該去哪邊找呢？

記得，除非有指定編譯結果的執行檔檔名，否則預設的執行檔檔名是 a.out。 用 `-o _filename_` 參數， 就可以達到所想要的結果，比如：

[source,bash]
....
% cc -o foobar foobar.c
....

==== 好，有個編譯好的程式叫做 foobar， 用 ls 指令時可以看到， 但執行時，訊息卻說卻沒有這檔案。為什麼？

與 不同的是，除非有指定執行檔的路徑， 否則 系統並不會在目前的目錄下尋找你想執行的檔案。 在指令列下打 `./foobar` 代表 "執行在這個目錄底下名為 [.filename]#foobar# 的程式"， 或者也可以更改 `PATH` 環境變數設定如下，以達成類似效果：

[source,bash]
....
bin:/usr/bin:/usr/local/bin:.
....

上一行最後的 "." 代表"如果在前面寫的其他目錄找不到，就找目前的目錄"。

==== 試著執行 test 執行檔， 但是卻沒有任何事發生，到底是哪裡出錯了？

大多數的 系統都會在路徑 [.filename]#/usr/bin# 擺放執行檔。 除非有指定使用在目前目錄內的 [.filename]#test#，否則 shell 會優先選擇位在 [.filename]#/usr/bin# 的 [.filename]#test#， 要指定檔名的話，作法類似：

[source,bash]
....
% ./test
....

為了避免上述困擾，請為你的程式取更好的名稱吧！

==== 當執行我寫的程式時剛開始正常， 接下來卻出現 core dumped 錯誤訊息。這錯誤訊息到底代表什麼？

關於 _core dumped_ 這個名稱的由來， 可以追溯到早期的 系統開始使用 core memory 對資料排序時。 基本上當程式在很多情況下發生錯誤後， 作業系統會把 core memory 中的資訊寫入 [.filename]#core# 這檔案中， 以便讓 programmer 知道程式到底是為何出錯。

==== 真是太神奇了！程式居然發生 core dumped 了，該怎麼辦？

請用 `gdb` 來分析 core 結果(詳情請參考 <<debugging>>)。

==== 當程式已經把 core memory 資料 dump 出來後， 同時也出現另一個錯誤 segmentation fault 這意思是？

基本上，這個錯誤表示你的程式在記憶體中試著做一個嚴重的非法運作(illegal operation)， 就是被設計來保護整個作業系統免於被惡質的程式破壞，所以才會告訴你這個訊息。

最常造成"segmentation fault"的原因通常為：

* 試著對一個 NULL 的指標(pointer)作寫入的動作，如
+
[.programlisting]
....
char *foo = NULL;
strcpy(foo, "bang!");
....

* 使用一個尚未初始化(initialized)的指標，如：
+
[.programlisting]
....
char *foo;
strcpy(foo, "bang!");
....
+ 
尚未初始化的指標的初始值將會是隨機的，如果你夠幸運的話， 這個指標的初始值會指向 kernel 已經用到的記憶體位置， kernel 會結束掉這個程式以確保系統運作正常。如果你不夠幸運， 初始指到的記憶體位置是你程式必須要用到的資料結構(data structures)的位置， 當這個情形發生時程式將會當的不知其所以然。
* 試著寫入超過陣列(array)元素個數，如：
+
[.programlisting]
....
int bar[20];
bar[27] = 6;
....

* 試著讀寫在唯讀記憶體(read-only memory)中的資料，如：
+
[.programlisting]
....
char *foo = "My string";
strcpy(foo, "bang!");
....
+ 
UNIX(R) compilers often put string literals like `"My string"` into read-only areas of memory.
* Doing naughty things with `malloc()` and `free()`, eg
+
[.programlisting]
....
char bar[80];
free(bar);
....
+ 
or
+
[.programlisting]
....
char *foo = malloc(27);
free(foo);
free(foo);
....

Making one of these mistakes will not always lead to an error, but they are always bad practice. Some systems and compilers are more tolerant than others, which is why programs that ran well on one system can crash when you try them on an another.

==== Sometimes when I get a core dump it says bus error. It says in my UNIX(R) book that this means a hardware problem, but the computer still seems to be working. Is this true?

No, fortunately not (unless of course you really do have a hardware problem...). This is usually another way of saying that you accessed memory in a way you should not have.

==== This dumping core business sounds as though it could be quite useful, if I can make it happen when I want to. Can I do this, or do I have to wait until there is an error?

Yes, just go to another console or xterm, do

[source,bash]
....
% ps
....

to find out the process ID of your program, and do

[source,bash]
....
% kill -ABRT pid
....

where `_pid_` is the process ID you looked up.

This is useful if your program has got stuck in an infinite loop, for instance. If your program happens to trap SIGABRT, there are several other signals which have a similar effect.

Alternatively, you can create a core dump from inside your program, by calling the `abort()` function. See the manual page of man:abort[3] to learn more.

If you want to create a core dump from outside your program, but do not want the process to terminate, you can use the `gcore` program. See the manual page of man:gcore[1] for more information.

[[tools-make]]
== Make

=== What is `make`?

When you are working on a simple program with only one or two source files, typing in

[source,bash]
....
% cc file1.c file2.c
....

is not too bad, but it quickly becomes very tedious when there are several files-and it can take a while to compile, too.

One way to get around this is to use object files and only recompile the source file if the source code has changed. So we could have something like:

[source,bash]
....
% cc file1.o file2.o … file37.c …
....

if we had changed [.filename]#file37.c#, but not any of the others, since the last time we compiled. This may speed up the compilation quite a bit, but does not solve the typing problem.

Or we could write a shell script to solve the typing problem, but it would have to re-compile everything, making it very inefficient on a large project.

What happens if we have hundreds of source files lying about? What if we are working in a team with other people who forget to tell us when they have changed one of their source files that we use?

Perhaps we could put the two solutions together and write something like a shell script that would contain some kind of magic rule saying when a source file needs compiling. Now all we need now is a program that can understand these rules, as it is a bit too complicated for the shell.

This program is called `make`. It reads in a file, called a _makefile_, that tells it how different files depend on each other, and works out which files need to be re-compiled and which ones do not. For example, a rule could say something like "if [.filename]#fromboz.o# is older than [.filename]#fromboz.c#, that means someone must have changed [.filename]#fromboz.c#, so it needs to be re-compiled." The makefile also has rules telling make _how_ to re-compile the source file, making it a much more powerful tool.

Makefiles are typically kept in the same directory as the source they apply to, and can be called [.filename]#makefile#, [.filename]#Makefile# or [.filename]#MAKEFILE#. Most programmers use the name [.filename]#Makefile#, as this puts it near the top of a directory listing, where it can easily be seen.footnote:[They do not use the MAKEFILE form as block capitals are often used for documentation files like README.]

=== Example of Using `make`

Here is a very simple make file:

[.programlisting]
....
foo: foo.c
	cc -o foo foo.c
....

It consists of two lines, a dependency line and a creation line.

The dependency line here consists of the name of the program (known as the _target_), followed by a colon, then whitespace, then the name of the source file. When `make` reads this line, it looks to see if [.filename]#foo# exists; if it exists, it compares the time [.filename]#foo# was last modified to the time [.filename]#foo.c# was last modified. If [.filename]#foo# does not exist, or is older than [.filename]#foo.c#, it then looks at the creation line to find out what to do. In other words, this is the rule for working out when [.filename]#foo.c# needs to be re-compiled.

The creation line starts with a tab (press kbd:[tab]) and then the command you would type to create [.filename]#foo# if you were doing it at a command prompt. If [.filename]#foo# is out of date, or does not exist, `make` then executes this command to create it. In other words, this is the rule which tells make how to re-compile [.filename]#foo.c#.

So, when you type `make`, it will make sure that [.filename]#foo# is up to date with respect to your latest changes to [.filename]#foo.c#. This principle can be extended to [.filename]#Makefile#'s with hundreds of targets-in fact, on FreeBSD, it is possible to compile the entire operating system just by typing `make world` in the appropriate directory!

Another useful property of makefiles is that the targets do not have to be programs. For instance, we could have a make file that looks like this:

[.programlisting]
....
foo: foo.c
	cc -o foo foo.c

install:
	cp foo /home/me
....

We can tell make which target we want to make by typing:

[source,bash]
....
% make target
....

`make` will then only look at that target and ignore any others. For example, if we type `make foo` with the makefile above, make will ignore the `install` target.

If we just type `make` on its own, make will always look at the first target and then stop without looking at any others. So if we typed `make` here, it will just go to the `foo` target, re-compile [.filename]#foo# if necessary, and then stop without going on to the `install` target.

Notice that the `install` target does not actually depend on anything! This means that the command on the following line is always executed when we try to make that target by typing `make install`. In this case, it will copy [.filename]#foo# into the user's home directory. This is often used by application makefiles, so that the application can be installed in the correct directory when it has been correctly compiled.

This is a slightly confusing subject to try to explain. If you do not quite understand how `make` works, the best thing to do is to write a simple program like "hello world" and a make file like the one above and experiment. Then progress to using more than one source file, or having the source file include a header file. `touch` is very useful here-it changes the date on a file without you having to edit it.

=== Make and include-files

C code often starts with a list of files to include, for example stdio.h. Some of these files are system-include files, some of them are from the project you are now working on:

[.programlisting]
....
#include <stdio.h>
#include "foo.h"

int main(....
....

To make sure that this file is recompiled the moment [.filename]#foo.h# is changed, you have to add it in your [.filename]#Makefile#:

[.programlisting]
....
foo: foo.c foo.h
....

The moment your project is getting bigger and you have more and more own include-files to maintain, it will be a pain to keep track of all include files and the files which are depending on it. If you change an include-file but forget to recompile all the files which are depending on it, the results will be devastating. `clang` has an option to analyze your files and to produce a list of include-files and their dependencies: `-MM`.

If you add this to your Makefile:

[.programlisting]
....
depend:
	cc -E -MM *.c > .depend
....

and run `make depend`, the file [.filename]#.depend# will appear with a list of object-files, C-files and the include-files:

[.programlisting]
....
foo.o: foo.c foo.h
....

If you change [.filename]#foo.h#, next time you run `make` all files depending on [.filename]#foo.h# will be recompiled.

Do not forget to run `make depend` each time you add an include-file to one of your files.

=== FreeBSD Makefiles

Makefiles can be rather complicated to write. Fortunately, BSD-based systems like FreeBSD come with some very powerful ones as part of the system. One very good example of this is the FreeBSD ports system. Here is the essential part of a typical ports [.filename]#Makefile#:

[.programlisting]
....
MASTER_SITES=   ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
DISTFILES=      scheme-microcode+dist-7.3-freebsd.tgz

.include <bsd.port.mk>
....

Now, if we go to the directory for this port and type `make`, the following happens:

[.procedure]
====
. A check is made to see if the source code for this port is already on the system.
. If it is not, an FTP connection to the URL in MASTER_SITES is set up to download the source.
. The checksum for the source is calculated and compared it with one for a known, good, copy of the source. This is to make sure that the source was not corrupted while in transit.
. Any changes required to make the source work on FreeBSD are applied-this is known as _patching_.
. Any special configuration needed for the source is done. (Many UNIX(R) program distributions try to work out which version of UNIX(R) they are being compiled on and which optional UNIX(R) features are present-this is where they are given the information in the FreeBSD ports scenario).
. The source code for the program is compiled. In effect, we change to the directory where the source was unpacked and do `make`-the program's own make file has the necessary information to build the program.
. We now have a compiled version of the program. If we wish, we can test it now; when we feel confident about the program, we can type `make install`. This will cause the program and any supporting files it needs to be copied into the correct location; an entry is also made into a `package database`, so that the port can easily be uninstalled later if we change our mind about it.
====

Now I think you will agree that is rather impressive for a four line script!

The secret lies in the last line, which tells `make` to look in the system makefile called [.filename]#bsd.port.mk#. It is easy to overlook this line, but this is where all the clever stuff comes from-someone has written a makefile that tells `make` to do all the things above (plus a couple of other things I did not mention, including handling any errors that may occur) and anyone can get access to that just by putting a single line in their own make file!

If you want to have a look at these system makefiles, they are in [.filename]#/usr/shared/mk#, but it is probably best to wait until you have had a bit of practice with makefiles, as they are very complicated (and if you do look at them, make sure you have a flask of strong coffee handy!)

=== More Advanced Uses of `make`

`Make` is a very powerful tool, and can do much more than the simple example above shows. Unfortunately, there are several different versions of `make`, and they all differ considerably. The best way to learn what they can do is probably to read the documentation-hopefully this introduction will have given you a base from which you can do this.

The version of make that comes with FreeBSD is the Berkeley make; there is a tutorial for it in [.filename]#/usr/shared/doc/psd/12.make#. To view it, do

[source,bash]
....
% zmore paper.ascii.gz
....

in that directory.

Many applications in the ports use GNU make, which has a very good set of "info" pages. If you have installed any of these ports, GNU make will automatically have been installed as `gmake`. It is also available as a port and package in its own right.

To view the info pages for GNU make, you will have to edit [.filename]#dir# in the [.filename]#/usr/local/info# directory to add an entry for it. This involves adding a line like

[.programlisting]
....
 * Make: (make).                 The GNU Make utility.
....

to the file. Once you have done this, you can type `info` and then select [.guimenuitem]#make# from the menu (or in Emacs, do `C-h i`).

[[debugging]]
== Debugging

=== Introduction to Available Debuggers

Using a debugger allows running the program under more controlled circumstances. Typically, it is possible to step through the program a line at a time, inspect the value of variables, change them, tell the debugger to run up to a certain point and then stop, and so on. It is also possible to attach to a program that is already running, or load a core file to investigate why the program crashed. It is even possible to debug the kernel, though that is a little trickier than the user applications we will be discussing in this section.

This section is intended to be a quick introduction to using debuggers and does not cover specialized topics such as debugging the kernel. For more information about that, refer to <<kerneldebug>>.

The standard debugger supplied with FreeBSD {rel121-current} is called `lldb` (LLVM debugger). As it is part of the standard installation for that release, there is no need to do anything special to use it. It has good command help, accessible via the `help` command, as well as https://lldb.llvm.org/[a web tutorial and documentation].

[NOTE]
====
The `lldb` command is available for FreeBSD {rel113-current} link:{handbook}#ports-using/[from ports or packages] as package:devel/llvm[]. This will install the default version of lldb (currently 9.0).
====

The other debugger available with FreeBSD is called `gdb` (GNU debugger). Unlike lldb, it is not installed by default on FreeBSD {rel121-current}; to use it, link:{handbook}#ports-using/[install] package:devel/gdb[] from ports or packages. The version installed by default on FreeBSD {rel113-current} is old; instead, install package:devel/gdb[] there as well. It has quite good on-line help, as well as a set of info pages.

Which one to use is largely a matter of taste. If familiar with one only, use that one. People familiar with neither or both but wanting to use one from inside Emacs will need to use `gdb` as `lldb` is unsupported by Emacs. Otherwise, try both and see which one you prefer.

=== Using lldb

==== Starting lldb

Start up lldb by typing

[source,bash]
....
% lldb -- progname
....

==== Running a Program with lldb

Compile the program with `-g` to get the most out of using `lldb`. It will work without, but will only display the name of the function currently running, instead of the source code. If it displays a line like:

[source,bash]
....
Breakpoint 1: where = temp`main, address = …
....

(without an indication of source code filename and line number) when setting a breakpoint, this means that the program was not compiled with `-g`.

[TIP]
====

Most `lldb` commands have shorter forms that can be used instead. The longer forms are used here for clarity.
====

At the `lldb` prompt, type `breakpoint set -n main`. This will tell the debugger not to display the preliminary set-up code in the program being run and to stop execution at the beginning of the program's code. Now type `process launch` to actually start the program- it will start at the beginning of the set-up code and then get stopped by the debugger when it calls `main()`.

To step through the program a line at a time, type `thread step-over`. When the program gets to a function call, step into it by typing `thread step-in`. Once in a function call, return from it by typing `thread step-out` or use `up` and `down` to take a quick look at the caller.

Here is a simple example of how to spot a mistake in a program with `lldb`. This is our program (with a deliberate mistake):

[.programlisting]
....
#include <stdio.h>

int bazz(int anint);

main() {
	int i;

	printf("This is my program\n");
	bazz(i);
	return 0;
}

int bazz(int anint) {
	printf("You gave me %d\n", anint);
	return anint;
}
....

This program sets i to be `5` and passes it to a function `bazz()` which prints out the number we gave it.

Compiling and running the program displays

[source,bash]
....
% cc -g -o temp temp.c
% ./temp
This is my program
anint = -5360
....

That is not what was expected! Time to see what is going on!

[source,bash]
....
% lldb -- temp
(lldb) target create "temp"
Current executable set to 'temp' (x86_64).
(lldb) breakpoint set -n main				Skip the set-up code
Breakpoint 1: where = temp`main + 15 at temp.c:8:2, address = 0x00000000002012ef	lldb puts breakpoint at main()
(lldb) process launch					Run as far as main()
Process 9992 launching
Process 9992 launched: '/home/pauamma/tmp/temp' (x86_64)	Program starts running

Process 9992 stopped
* thread #1, name = 'temp', stop reason = breakpoint 1.1	lldb stops at main()
    frame #0: 0x00000000002012ef temp`main at temp.c:8:2
   5	main() {
   6		int i;
   7
-> 8		printf("This is my program\n");			Indicates the line where it stopped
   9		bazz(i);
   10		return 0;
   11	}
(lldb) thread step-over			Go to next line
This is my program						Program prints out
Process 9992 stopped
* thread #1, name = 'temp', stop reason = step over
    frame #0: 0x0000000000201300 temp`main at temp.c:9:7
   6		int i;
   7
   8		printf("This is my program\n");
-> 9		bazz(i);
   10		return 0;
   11	}
   12
(lldb) thread step-in			step into bazz()
Process 9992 stopped
* thread #1, name = 'temp', stop reason = step in
    frame #0: 0x000000000020132b temp`bazz(anint=-5360) at temp.c:14:29	lldb displays stack frame
   11	}
   12
   13	int bazz(int anint) {
-> 14		printf("You gave me %d\n", anint);
   15		return anint;
   16	}
(lldb)
....

Hang on a minute! How did anint get to be `-5360`? Was it not set to `5` in `main()`? Let us move up to `main()` and have a look.

[source,bash]
....
(lldb) up		Move up call stack
frame #1: 0x000000000020130b temp`main at temp.c:9:2		lldb displays stack frame
   6		int i;
   7
   8		printf("This is my program\n");
-> 9		bazz(i);
   10		return 0;
   11	}
   12
(lldb) frame variable i			Show us the value of i
(int) i = -5360							lldb displays -5360
....

Oh dear! Looking at the code, we forgot to initialize i. We meant to put

[.programlisting]
....
...
main() {
	int i;

	i = 5;
	printf("This is my program\n");
...
....

but we left the `i=5;` line out. As we did not initialize i, it had whatever number happened to be in that area of memory when the program ran, which in this case happened to be `-5360`.

[NOTE]
====
The `lldb` command displays the stack frame every time we go into or out of a function, even if we are using `up` and `down` to move around the call stack. This shows the name of the function and the values of its arguments, which helps us keep track of where we are and what is going on. (The stack is a storage area where the program stores information about the arguments passed to functions and where to go when it returns from a function call.)
====

==== Examining a Core File with lldb

A core file is basically a file which contains the complete state of the process when it crashed. In "the good old days", programmers had to print out hex listings of core files and sweat over machine code manuals, but now life is a bit easier. Incidentally, under FreeBSD and other 4.4BSD systems, a core file is called [.filename]#progname.core# instead of just [.filename]#core#, to make it clearer which program a core file belongs to.

To examine a core file, specify the name of the core file in addition to the program itself. Instead of starting up `lldb` in the usual way, type `lldb -c _progname_.core -- _progname_`

The debugger will display something like this:

[source,bash,subs="verbatim,quotes"]
....
% lldb -c [.filename]#progname.core# -- [.filename]#progname#
(lldb) target create "[.filename]#progname#" --core "[.filename]#progname#.core"
Core file '/home/pauamma/tmp/[.filename]#progname.core#' (x86_64) was loaded.
(lldb)
....

In this case, the program was called [.filename]#progname#, so the core file is called [.filename]#progname.core#. The debugger does not display why the program crashed or where. For this, use `thread backtrace all`. This will also show how the function where the program dumped core was called.

[source,bash,subs="verbatim,quotes"]
....
(lldb) thread backtrace all
* thread #1, name = 'progname', stop reason = signal SIGSEGV
  * frame #0: 0x0000000000201347 progname`bazz(anint=5) at temp2.c:17:10
    frame #1: 0x0000000000201312 progname`main at temp2.c:10:2
    frame #2: 0x000000000020110f progname`_start(ap=<unavailable>, cleanup=<unavailable>) at crt1.c:76:7
(lldb)
....

`SIGSEGV` indicates that the program tried to access memory (run code or read/write data usually) at a location that does not belong to it, but does not give any specifics. For that, look at the source code at line 10 of file temp2.c, in `bazz()`. The backtrace also says that in this case, `bazz()` was called from `main()`.

==== Attaching to a Running Program with lldb

One of the neatest features about `lldb` is that it can attach to a program that is already running. Of course, that requires sufficient permissions to do so. A common problem is stepping through a program that forks and wanting to trace the child, but the debugger will only trace the parent.

To do that, start up another `lldb`, use `ps` to find the process ID for the child, and do

[source,bash]
....
(lldb) process attach -p pid
....

in `lldb`, and then debug as usual.

For that to work well, the code that calls `fork` to create the child needs to do something like the following (courtesy of the `gdb` info pages):

[.programlisting]
....
...
if ((pid = fork()) < 0)		/* _Always_ check this */
	error();
else if (pid == 0) {		/* child */
	int PauseMode = 1;

	while (PauseMode)
		sleep(10);	/* Wait until someone attaches to us */
	...
} else {			/* parent */
	...
....

Now all that is needed is to attach to the child, set PauseMode to `0` with `expr PauseMode = 0` and wait for the `sleep()` call to return.

=== Using gdb

==== Starting gdb

Start up gdb by typing

[source,bash]
....
% gdb progname
....

although many people prefer to run it inside Emacs. To do this, type:

[source,bash]
....
 M-x gdb RET progname RET
....

Finally, for those finding its text-based command-prompt style off-putting, there is a graphical front-end for it (package:devel/xxgdb[]) in the Ports Collection.

==== Running a Program with gdb

Compile the program with `-g` to get the most out of using `gdb`. It will work without, but will only display the name of the function currently running, instead of the source code. A line like:

[source,bash]
....
... (no debugging symbols found) ...
....

when `gdb` starts up means that the program was not compiled with `-g`.

At the `gdb` prompt, type `break main`. This will tell the debugger to skip the preliminary set-up code in the program being run and to stop execution at the beginning of the program's code. Now type `run` to start the program- it will start at the beginning of the set-up code and then get stopped by the debugger when it calls `main()`.

To step through the program a line at a time, press `n`. When at a function call, step into it by pressing `s`. Once in a function call, return from it by pressing `f`, or use `up` and `down` to take a quick look at the caller.

Here is a simple example of how to spot a mistake in a program with `gdb`. This is our program (with a deliberate mistake):

[.programlisting]
....
#include <stdio.h>

int bazz(int anint);

main() {
	int i;

	printf("This is my program\n");
	bazz(i);
	return 0;
}

int bazz(int anint) {
	printf("You gave me %d\n", anint);
	return anint;
}
....

This program sets i to be `5` and passes it to a function `bazz()` which prints out the number we gave it.

Compiling and running the program displays

[source,bash]
....
% cc -g -o temp temp.c
% ./temp
This is my program
anint = 4231
....

That was not what we expected! Time to see what is going on!

[source,bash]
....
% gdb temp
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
(gdb) break main				Skip the set-up code
Breakpoint 1 at 0x160f: file temp.c, line 9.	gdb puts breakpoint at main()
(gdb) run					Run as far as main()
Starting program: /home/james/tmp/temp		Program starts running

Breakpoint 1, main () at temp.c:9		gdb stops at main()
(gdb) n						Go to next line
This is my program				Program prints out
(gdb) s						step into bazz()
bazz (anint=4231) at temp.c:17			gdb displays stack frame
(gdb)
....

Hang on a minute! How did anint get to be `4231`? Was it not set to `5` in `main()`? Let us move up to `main()` and have a look.

[source,bash]
....
(gdb) up					Move up call stack
#1  0x1625 in main () at temp.c:11		gdb displays stack frame
(gdb) p i					Show us the value of i
$1 = 4231					gdb displays 4231
....

Oh dear! Looking at the code, we forgot to initialize i. We meant to put

[.programlisting]
....
...
main() {
	int i;

	i = 5;
	printf("This is my program\n");
...
....

but we left the `i=5;` line out. As we did not initialize i, it had whatever number happened to be in that area of memory when the program ran, which in this case happened to be `4231`.

[NOTE]
====
The `gdb` command displays the stack frame every time we go into or out of a function, even if we are using `up` and `down` to move around the call stack. This shows the name of the function and the values of its arguments, which helps us keep track of where we are and what is going on. (The stack is a storage area where the program stores information about the arguments passed to functions and where to go when it returns from a function call.)
====

==== Examining a Core File with gdb

A core file is basically a file which contains the complete state of the process when it crashed. In "the good old days", programmers had to print out hex listings of core files and sweat over machine code manuals, but now life is a bit easier. Incidentally, under FreeBSD and other 4.4BSD systems, a core file is called [.filename]#progname.core# instead of just [.filename]#core#, to make it clearer which program a core file belongs to.

To examine a core file, start up `gdb` in the usual way. Instead of typing `break` or `run`, type

[source,bash]
....
(gdb) core progname.core
....

If the core file is not in the current directory, type `dir /path/to/core/file` first.

The debugger should display something like this:

[source,bash,subs="verbatim,quotes"]
....
% gdb [.filename]#progname#
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
(gdb) core [.filename]#progname.core#
Core was generated by `[.filename]#progname#'.
Program terminated with signal 11, Segmentation fault.
Cannot access memory at address 0x7020796d.
#0  0x164a in bazz (anint=0x5) at temp.c:17
(gdb)
....

In this case, the program was called [.filename]#progname#, so the core file is called [.filename]#progname.core#. We can see that the program crashed due to trying to access an area in memory that was not available to it in a function called `bazz`.

Sometimes it is useful to be able to see how a function was called, as the problem could have occurred a long way up the call stack in a complex program. `bt` causes `gdb` to print out a back-trace of the call stack:

[source,bash]
....
(gdb) bt
#0  0x164a in bazz (anint=0x5) at temp.c:17
#1  0xefbfd888 in end ()
#2  0x162c in main () at temp.c:11
(gdb)
....

The `end()` function is called when a program crashes; in this case, the `bazz()` function was called from `main()`.

==== Attaching to a Running Program with gdb

One of the neatest features about `gdb` is that it can attach to a program that is already running. Of course, that requires sufficient permissions to do so. A common problem is stepping through a program that forks and wanting to trace the child, but the debugger will only trace the parent.

To do that, start up another `gdb`, use `ps` to find the process ID for the child, and do

[source,bash]
....
(gdb) attach pid
....

in `gdb`, and then debug as usual.

For that to work well, the code that calls `fork` to create the child needs to do something like the following (courtesy of the `gdb` info pages):

[.programlisting]
....
...
if ((pid = fork()) < 0)		/* _Always_ check this */
	error();
else if (pid == 0) {		/* child */
	int PauseMode = 1;

	while (PauseMode)
		sleep(10);	/* Wait until someone attaches to us */
	...
} else {			/* parent */
	...
....

Now all that is needed is to attach to the child, set PauseMode to `0`, and wait for the `sleep()` call to return!

[[emacs]]
== Using Emacs as a Development Environment

=== Emacs

Emacs is a highly customizable editor-indeed, it has been customized to the point where it is more like an operating system than an editor! Many developers and sysadmins do in fact spend practically all their time working inside Emacs, leaving it only to log out.

It is impossible even to summarize everything Emacs can do here, but here are some of the features of interest to developers:

* Very powerful editor, allowing search-and-replace on both strings and regular expressions (patterns), jumping to start/end of block expression, etc, etc.
* Pull-down menus and online help.
* Language-dependent syntax highlighting and indentation.
* Completely customizable.
* You can compile and debug programs within Emacs.
* On a compilation error, you can jump to the offending line of source code.
* Friendly-ish front-end to the `info` program used for reading GNU hypertext documentation, including the documentation on Emacs itself.
* Friendly front-end to `gdb`, allowing you to look at the source code as you step through your program.

And doubtless many more that have been overlooked.

Emacs can be installed on FreeBSD using the package:editors/emacs[] port.

Once it is installed, start it up and do `C-h t` to read an Emacs tutorial-that means hold down kbd:[control], press kbd:[h], let go of kbd:[control], and then press kbd:[t]. (Alternatively, you can use the mouse to select [.guimenuitem]#Emacs Tutorial# from the menu:Help[] menu.)

Although Emacs does have menus, it is well worth learning the key bindings, as it is much quicker when you are editing something to press a couple of keys than to try to find the mouse and then click on the right place. And, when you are talking to seasoned Emacs users, you will find they often casually throw around expressions like "`M-x replace-s RET foo RET bar RET`" so it is useful to know what they mean. And in any case, Emacs has far too many useful functions for them to all fit on the menu bars.

Fortunately, it is quite easy to pick up the key-bindings, as they are displayed next to the menu item. My advice is to use the menu item for, say, opening a file until you understand how it works and feel confident with it, then try doing C-x C-f. When you are happy with that, move on to another menu command.

If you cannot remember what a particular combination of keys does, select [.guimenuitem]#Describe Key# from the menu:Help[] menu and type it in-Emacs will tell you what it does. You can also use the [.guimenuitem]#Command Apropos# menu item to find out all the commands which contain a particular word in them, with the key binding next to it.

By the way, the expression above means hold down the kbd:[Meta] key, press kbd:[x], release the kbd:[Meta] key, type `replace-s` (short for `replace-string`-another feature of Emacs is that you can abbreviate commands), press the kbd:[return] key, type `foo` (the string you want replaced), press the kbd:[return] key, type bar (the string you want to replace `foo` with) and press kbd:[return] again. Emacs will then do the search-and-replace operation you have just requested.

If you are wondering what on earth kbd:[Meta] is, it is a special key that many UNIX(R) workstations have. Unfortunately, PC's do not have one, so it is usually kbd:[alt] (or if you are unlucky, the kbd:[escape] key).

Oh, and to get out of Emacs, do `C-x C-c` (that means hold down the kbd:[control] key, press kbd:[x], press kbd:[c] and release the kbd:[control] key). If you have any unsaved files open, Emacs will ask you if you want to save them. (Ignore the bit in the documentation where it says `C-z` is the usual way to leave Emacs-that leaves Emacs hanging around in the background, and is only really useful if you are on a system which does not have virtual terminals).

=== Configuring Emacs

Emacs does many wonderful things; some of them are built in, some of them need to be configured.

Instead of using a proprietary macro language for configuration, Emacs uses a version of Lisp specially adapted for editors, known as Emacs Lisp. Working with Emacs Lisp can be quite helpful if you want to go on and learn something like Common Lisp. Emacs Lisp has many features of Common Lisp, although it is considerably smaller (and thus easier to master).

The best way to learn Emacs Lisp is to download the link:ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz[Emacs Tutorial]

However, there is no need to actually know any Lisp to get started with configuring Emacs, as I have included a sample [.filename]#.emacs#, which should be enough to get you started. Just copy it into your home directory and restart Emacs if it is already running; it will read the commands from the file and (hopefully) give you a useful basic setup.

=== A Sample [.filename]#.emacs#

Unfortunately, there is far too much here to explain it in detail; however there are one or two points worth mentioning.

* Everything beginning with a `;` is a comment and is ignored by Emacs.
* In the first line, the `-*- Emacs-Lisp -*-` is so that we can edit [.filename]#.emacs# itself within Emacs and get all the fancy features for editing Emacs Lisp. Emacs usually tries to guess this based on the filename, and may not get it right for [.filename]#.emacs#.
* The kbd:[tab] key is bound to an indentation function in some modes, so when you press the tab key, it will indent the current line of code. If you want to put a tab character in whatever you are writing, hold the kbd:[control] key down while you are pressing the kbd:[tab] key.
* This file supports syntax highlighting for C, C++, Perl, Lisp and Scheme, by guessing the language from the filename.
* Emacs already has a pre-defined function called `next-error`. In a compilation output window, this allows you to move from one compilation error to the next by doing `M-n`; we define a complementary function, `previous-error`, that allows you to go to a previous error by doing `M-p`. The nicest feature of all is that `C-c C-c` will open up the source file in which the error occurred and jump to the appropriate line.
* We enable Emacs's ability to act as a server, so that if you are doing something outside Emacs and you want to edit a file, you can just type in
+
[source,bash]
....
% emacsclient filename
....
+ 
and then you can edit the file in your Emacs!footnote:[Many Emacs users set their EDITOR environment to emacsclient so this happens every time they need to edit a file.]

.A Sample [.filename]#.emacs#
====
[.programlisting]
....
;; -*-Emacs-Lisp-*-

;; This file is designed to be re-evaled; use the variable first-time
;; to avoid any problems with this.
(defvar first-time t
  "Flag signifying this is the first time that .emacs has been evaled")

;; Meta
(global-set-key "\M- " 'set-mark-command)
(global-set-key "\M-\C-h" 'backward-kill-word)
(global-set-key "\M-\C-r" 'query-replace)
(global-set-key "\M-r" 'replace-string)
(global-set-key "\M-g" 'goto-line)
(global-set-key "\M-h" 'help-command)

;; Function keys
(global-set-key [f1] 'manual-entry)
(global-set-key [f2] 'info)
(global-set-key [f3] 'repeat-complex-command)
(global-set-key [f4] 'advertised-undo)
(global-set-key [f5] 'eval-current-buffer)
(global-set-key [f6] 'buffer-menu)
(global-set-key [f7] 'other-window)
(global-set-key [f8] 'find-file)
(global-set-key [f9] 'save-buffer)
(global-set-key [f10] 'next-error)
(global-set-key [f11] 'compile)
(global-set-key [f12] 'grep)
(global-set-key [C-f1] 'compile)
(global-set-key [C-f2] 'grep)
(global-set-key [C-f3] 'next-error)
(global-set-key [C-f4] 'previous-error)
(global-set-key [C-f5] 'display-faces)
(global-set-key [C-f8] 'dired)
(global-set-key [C-f10] 'kill-compilation)

;; Keypad bindings
(global-set-key [up] "\C-p")
(global-set-key [down] "\C-n")
(global-set-key [left] "\C-b")
(global-set-key [right] "\C-f")
(global-set-key [home] "\C-a")
(global-set-key [end] "\C-e")
(global-set-key [prior] "\M-v")
(global-set-key [next] "\C-v")
(global-set-key [C-up] "\M-\C-b")
(global-set-key [C-down] "\M-\C-f")
(global-set-key [C-left] "\M-b")
(global-set-key [C-right] "\M-f")
(global-set-key [C-home] "\M-<")
(global-set-key [C-end] "\M->")
(global-set-key [C-prior] "\M-<")
(global-set-key [C-next] "\M->")

;; Mouse
(global-set-key [mouse-3] 'imenu)

;; Misc
(global-set-key [C-tab] "\C-q\t")	; Control tab quotes a tab.
(setq backup-by-copying-when-mismatch t)

;; Treat 'y' or <CR> as yes, 'n' as no.
(fset 'yes-or-no-p 'y-or-n-p)
(define-key query-replace-map [return] 'act)
(define-key query-replace-map [?\C-m] 'act)

;; Load packages
(require 'desktop)
(require 'tar-mode)

;; Pretty diff mode
(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t)
(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t)
(autoload 'ediff-files-remote "ediff"
  "Intelligent Emacs interface to diff")

(if first-time
    (setq auto-mode-alist
	  (append '(("\\.cpp$" . c++-mode)
		    ("\\.hpp$" . c++-mode)
		    ("\\.lsp$" . lisp-mode)
		    ("\\.scm$" . scheme-mode)
		    ("\\.pl$" . perl-mode)
		    ) auto-mode-alist)))

;; Auto font lock mode
(defvar font-lock-auto-mode-list
  (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode)
  "List of modes to always start in font-lock-mode")

(defvar font-lock-mode-keyword-alist
  '((c++-c-mode . c-font-lock-keywords)
    (perl-mode . perl-font-lock-keywords))
  "Associations between modes and keywords")

(defun font-lock-auto-mode-select ()
  "Automatically select font-lock-mode if the current major mode is in font-lock-auto-mode-list"
  (if (memq major-mode font-lock-auto-mode-list)
      (progn
	(font-lock-mode t))
    )
  )

(global-set-key [M-f1] 'font-lock-fontify-buffer)

;; New dabbrev stuff
;(require 'new-dabbrev)
(setq dabbrev-always-check-other-buffers t)
(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_")
(add-hook 'emacs-lisp-mode-hook
	  '(lambda ()
	     (set (make-local-variable 'dabbrev-case-fold-search) nil)
	     (set (make-local-variable 'dabbrev-case-replace) nil)))
(add-hook 'c-mode-hook
	  '(lambda ()
	     (set (make-local-variable 'dabbrev-case-fold-search) nil)
	     (set (make-local-variable 'dabbrev-case-replace) nil)))
(add-hook 'text-mode-hook
	  '(lambda ()
	     (set (make-local-variable 'dabbrev-case-fold-search) t)
	     (set (make-local-variable 'dabbrev-case-replace) t)))

;; C++ and C mode...
(defun my-c++-mode-hook ()
  (setq tab-width 4)
  (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
  (define-key c++-mode-map "\C-ce" 'c-comment-edit)
  (setq c++-auto-hungry-initial-state 'none)
  (setq c++-delete-function 'backward-delete-char)
  (setq c++-tab-always-indent t)
  (setq c-indent-level 4)
  (setq c-continued-statement-offset 4)
  (setq c++-empty-arglist-indent 4))

(defun my-c-mode-hook ()
  (setq tab-width 4)
  (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent)
  (define-key c-mode-map "\C-ce" 'c-comment-edit)
  (setq c-auto-hungry-initial-state 'none)
  (setq c-delete-function 'backward-delete-char)
  (setq c-tab-always-indent t)
;; BSD-ish indentation style
  (setq c-indent-level 4)
  (setq c-continued-statement-offset 4)
  (setq c-brace-offset -4)
  (setq c-argdecl-indent 0)
  (setq c-label-offset -4))

;; Perl mode
(defun my-perl-mode-hook ()
  (setq tab-width 4)
  (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
  (setq perl-indent-level 4)
  (setq perl-continued-statement-offset 4))

;; Scheme mode...
(defun my-scheme-mode-hook ()
  (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent))

;; Emacs-Lisp mode...
(defun my-lisp-mode-hook ()
  (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent)
  (define-key lisp-mode-map "\C-i" 'lisp-indent-line)
  (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp))

;; Add all of the hooks...
(add-hook 'c++-mode-hook 'my-c++-mode-hook)
(add-hook 'c-mode-hook 'my-c-mode-hook)
(add-hook 'scheme-mode-hook 'my-scheme-mode-hook)
(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook)
(add-hook 'lisp-mode-hook 'my-lisp-mode-hook)
(add-hook 'perl-mode-hook 'my-perl-mode-hook)

;; Complement to next-error
(defun previous-error (n)
  "Visit previous compilation error message and corresponding source code."
  (interactive "p")
  (next-error (- n)))

;; Misc...
(transient-mark-mode 1)
(setq mark-even-if-inactive t)
(setq visible-bell nil)
(setq next-line-add-newlines nil)
(setq compile-command "make")
(setq suggest-key-bindings nil)
(put 'eval-expression 'disabled nil)
(put 'narrow-to-region 'disabled nil)
(put 'set-goal-column 'disabled nil)
(if (>= emacs-major-version 21)
	(setq show-trailing-whitespace t))

;; Elisp archive searching
(autoload 'format-lisp-code-directory "lispdir" nil t)
(autoload 'lisp-dir-apropos "lispdir" nil t)
(autoload 'lisp-dir-retrieve "lispdir" nil t)
(autoload 'lisp-dir-verify "lispdir" nil t)

;; Font lock mode
(defun my-make-face (face color &optional bold)
  "Create a face from a color and optionally make it bold"
  (make-face face)
  (copy-face 'default face)
  (set-face-foreground face color)
  (if bold (make-face-bold face))
  )

(if (eq window-system 'x)
    (progn
      (my-make-face 'blue "blue")
      (my-make-face 'red "red")
      (my-make-face 'green "dark green")
      (setq font-lock-comment-face 'blue)
      (setq font-lock-string-face 'bold)
      (setq font-lock-type-face 'bold)
      (setq font-lock-keyword-face 'bold)
      (setq font-lock-function-name-face 'red)
      (setq font-lock-doc-string-face 'green)
      (add-hook 'find-file-hooks 'font-lock-auto-mode-select)

      (setq baud-rate 1000000)
      (global-set-key "\C-cmm" 'menu-bar-mode)
      (global-set-key "\C-cms" 'scroll-bar-mode)
      (global-set-key [backspace] 'backward-delete-char)
					;      (global-set-key [delete] 'delete-char)
      (standard-display-european t)
      (load-library "iso-transl")))

;; X11 or PC using direct screen writes
(if window-system
    (progn
      ;;      (global-set-key [M-f1] 'hilit-repaint-command)
      ;;      (global-set-key [M-f2] [?\C-u M-f1])
      (setq hilit-mode-enable-list
	    '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode
		  scheme-mode)
	    hilit-auto-highlight nil
	    hilit-auto-rehighlight 'visible
	    hilit-inhibit-hooks nil
	    hilit-inhibit-rebinding t)
      (require 'hilit19)
      (require 'paren))
  (setq baud-rate 2400)			; For slow serial connections
  )

;; TTY type terminal
(if (and (not window-system)
	 (not (equal system-type 'ms-dos)))
    (progn
      (if first-time
	  (progn
	    (keyboard-translate ?\C-h ?\C-?)
	    (keyboard-translate ?\C-? ?\C-h)))))

;; Under UNIX
(if (not (equal system-type 'ms-dos))
    (progn
      (if first-time
	  (server-start))))

;; Add any face changes here
(add-hook 'term-setup-hook 'my-term-setup-hook)
(defun my-term-setup-hook ()
  (if (eq window-system 'pc)
      (progn
;;	(set-face-background 'default "red")
	)))

;; Restore the "desktop" - do this as late as possible
(if first-time
    (progn
      (desktop-load-default)
      (desktop-read)))

;; Indicate that this file has been read at least once
(setq first-time nil)

;; No need to debug anything now

(setq debug-on-error nil)

;; All done
(message "All done, %s%s" (user-login-name) ".")
....
====

=== Extending the Range of Languages Emacs Understands

Now, this is all very well if you only want to program in the languages already catered for in [.filename]#.emacs# (C, C++, Perl, Lisp and Scheme), but what happens if a new language called "whizbang" comes out, full of exciting features?

The first thing to do is find out if whizbang comes with any files that tell Emacs about the language. These usually end in [.filename]#.el#, short for "Emacs Lisp". For example, if whizbang is a FreeBSD port, we can locate these files by doing

[source,bash]
....
% find /usr/ports/lang/whizbang -name "*.el" -print
....

and install them by copying them into the Emacs site Lisp directory. On FreeBSD, this is [.filename]#/usr/local/shared/emacs/site-lisp#.

So for example, if the output from the find command was

[source,bash]
....
/usr/ports/lang/whizbang/work/misc/whizbang.el
....

we would do

[source,bash]
....
# cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/shared/emacs/site-lisp
....

Next, we need to decide what extension whizbang source files have. Let us say for the sake of argument that they all end in [.filename]#.wiz#. We need to add an entry to our [.filename]#.emacs# to make sure Emacs will be able to use the information in [.filename]#whizbang.el#.

Find the auto-mode-alist entry in [.filename]#.emacs# and add a line for whizbang, such as:

[.programlisting]
....
...
("\\.lsp$" . lisp-mode)
("\\.wiz$" . whizbang-mode)
("\\.scm$" . scheme-mode)
...
....

This means that Emacs will automatically go into `whizbang-mode` when you edit a file ending in [.filename]#.wiz#.

Just below this, you will find the font-lock-auto-mode-list entry. Add `whizbang-mode` to it like so:

[.programlisting]
....
;; Auto font lock mode
(defvar font-lock-auto-mode-list
  (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode)
  "List of modes to always start in font-lock-mode")
....

This means that Emacs will always enable `font-lock-mode` (ie syntax highlighting) when editing a [.filename]#.wiz# file.

And that is all that is needed. If there is anything else you want done automatically when you open up [.filename]#.wiz#, you can add a `whizbang-mode hook` (see `my-scheme-mode-hook` for a simple example that adds `auto-indent`).

[[tools-reading]]
== Further Reading

For information about setting up a development environment for contributing fixes to FreeBSD itself, please see man:development[7].

* Brian Harvey and Matthew Wright _Simply Scheme_ MIT 1994. ISBN 0-262-08226-8
* Randall Schwartz _Learning Perl_ O'Reilly 1993 ISBN 1-56592-042-2
* Patrick Henry Winston and Berthold Klaus Paul Horn _Lisp (3rd Edition)_ Addison-Wesley 1989 ISBN 0-201-08319-1
* Brian W. Kernighan and Rob Pike _The Unix Programming Environment_ Prentice-Hall 1984 ISBN 0-13-937681-X
* Brian W. Kernighan and Dennis M. Ritchie _The C Programming Language (2nd Edition)_ Prentice-Hall 1988 ISBN 0-13-110362-8
* Bjarne Stroustrup _The C++ Programming Language_ Addison-Wesley 1991 ISBN 0-201-53992-6
* W. Richard Stevens _Advanced Programming in the Unix Environment_ Addison-Wesley 1992 ISBN 0-201-56317-7
* W. Richard Stevens _Unix Network Programming_ Prentice-Hall 1990 ISBN 0-13-949876-1
