• Ubuntu Oneiric Ocelot 11.10 Test 완료. (2012-03-01)
  (apache2-mpm-prefork 2.2.20, libapache2-mod-passenger 2.2.11, mysql-server 5.1.58, redmine 1.3.0 & 1.3.2 & 1.3.3, ruby 4.8, ruby-rails 2.3.14, subversion 1.6.12, redmine_scm 0.3.0)

1. Redmine?

Redmine은 여러 Platform과 Database를 지원하는, Project 관리를 위한 Open-source Web Application입니다.

Redmine은 다음과 같은 기능을 지원합니다.

• 여러 Project 생성 가능
• Issue(Bug) 관리 System
• Gantt Chart와 Calendar 지원
• News, 문서, File 관리, Wiki, Forum 지원
• SCM과 Project 통합 (SVN, CVS, Git, Mercurial, Bazzar, Darcs)

개인적으로 생각하기에 MS Project와 같은 상용 Project 관리 Tool 보다는 부족한 기능을 갖고 있지만, 비교적 규모가 작은 Project를 RAD로 개발하는 경우에 유용한 것 같습니다. 특히 Eclipse의 Mylyn Plugin과의 연동은 개발자를 행복하게 만들어 줍니다.

Redmine의 보다 자세한 기능을 알기 원한다면 http://m.redmine.org에서 Demo 계정을 통해 관리자 권한으로 접속하여 사용해 보기 바랍니다.

2. 설치

Redmine은 Web Application이기 때문에 Web Server를 먼저 구축한 다음, Redmine을 설치해야 합니다. 설치하는 방법은 다음과 같습니다.

2.1. LAMP 설치

Ubuntu를 설치한 System를 Web Server로 만들기 위해 LAMP(Linux, Apache, MySQL, PHP) Stack을 설치합니다. 다음과 같이 Terminal에서 입력합니다.

Setting up MySQL root password

설치 중간에 위와 같은 화면이 나오면 MySQL의 관리자 계정에 대한 Password를 입력하고, 확인을 위해 한번 더 입력하면 됩니다.

2.2. Redmine 설치

Web Server는 LAMP Stack을 통해서 간단히 설치했으니, 이제 Redmine을 설치해 봅시다.

Ubuntu Repository에도 Redmine Package가 존재하지만 Version이 낮기 때문에, 최신의 Redmine을 설치하기 위하여 Launchpad PPA를 사용합시다. Terminal에서 다음과 같이 입력합니다.

Using dbconfig-common

설치 도중에 위와 같은 화면이 나오면 dbconfig-commmon을 사용하여 DB를 설정하기 위해 예를 선택하고 Enter를 누릅니다.

Setting up Redmine's DB type

Redmine에서 사용할 DB의 종류를 선택하는 화면에서 mysql을 선택하고 확인을 누릅니다.

Input MySQL root password

LAMP Stack을 설치할 때 입력했던 MySQL 관리자 계정의 암호를 입력합니다.

Input MySQL password for Redmine

MySQL에서 Redmine의 정보를 저장하는 DB 계정에 대한 Password를 입력하고, 확인을 위하여 한번 더 입력하면 설치가 완료됩니다.

이제 Web Server와 연동하기 위해서 Apache의 DocumentRoot인 /var/www에 Redmine 접속을 위한 Directory를 다음과 같이 Link합니다.

그 다음, Apache와 Redmine에서 Base로 사용하는 언어인 Ruby를 연동하는 Module인 Passenger를 설정하기위해 Terminal에서 다음과 같이 입력합니다.

<IfModule>과 </IfModule>사이에 다음과 같은 Line을 추가합니다.

그리고 Apache의 Default Site에 대한 설정을 수정하기 위해 다음과 같이 입력합니다.

<VirtualHost>와 </VirtualHost> 사이에 다음과 같은 Line을 추가합니다.

그리고 마지막으로 다음과 같이 입력하여 Apache를 재시작하면 Redmine의 설치가 완료됩니다.

2.3. Firewall 설정

Ubuntu의 UFW 방화벽을 사용한다면 다른 Client의 접속을 위해서 방화벽 설정을 변경해야 합니다.

UFW를 편리하게 설정할 수 있는 Gufw를 사용하여 방화벽 설정을 변경해 봅시다. 설치 방법은 Ubuntu Oneiric Ocelot 11.10을 설치한 후 해야 할 것들 (1. System 설정)을 참고하기 바랍니다.

Gufw

Gufw를 실행한 다음, 새로운 규칙을 추가하기 위해서 + Button을 누릅니다.

Gufw - Add rule

Add Rule Dialog에서 편리하게 Tab의 Service, HTTP를 선택하고 추가를 누르면 다른 Client에서 Web Server로 접속하기 위한 Rule이 UFW에 추가됩니다.

3. Redmine 설정

Redmine의 설치를 완료했으니 이제 Redmine을 사용하기 위한 기본 설정을 해 봅시다. 지면상 여기서는 모든 설정을 설명하지 않고 사용하는데 필요한 몇가지만 설명합니다.

Redmine을 설치한 Server에서 Web Browser를 실행한 다음, http://localhost/redmine을 입력하여 Redmine에 접속합니다.

Redmine - Index page

제대로 설치가 되었다면 위와 같은 Page를 표시할 것입니다. 관리자로 접속하기 위해서 오른쪽 위에 로그인을 Click합니다.

Redmine - Login

Login Page에서 다음과 같이 ID와 Password를 입력합니다.

• 로그인: admin
• 비밀번호: admin

Redmine - Index (Login)

관리자로 Login이 되었다면 먼저 관리자 ID인 admin의 Password를 변경해야 합니다. 오른쪽 위에 My Account를 Click합니다.

Redmine - My account

Password를 변경하기 위해서 Change password를 Click합니다.

Redmine - Change password

Password에는 기존의 Password인 admin을 입력하고, New password와 Confirmation에 새로운 Password를 입력하고 Apply를 누릅니다.

Redmine - My Account (Langauge)

그 다음에는 사용할 언어를 변경하기 위해서 Language를 한국어(Korean)으로 변경하고 Save를 누릅니다.

Redmine - Administration (Settings)

그 다음, Redmine의 기본 설정을 변경하기 위해서 왼쪽 위의 관리를 누른 다음, 설정을 누릅니다.

Redmine - Settings (Language)

사용자가 Redmine을 사용할 때 표시할 기본 언어를 변경하기 위해서 표시방식 Tab에서 기본 언어를 한국어(Korean)으로 변경하고 저장을 누릅니다.

Redmine - Settings (Encodings)

그리고 일반 Tab의 Attachments and repositories encodings는 첨부한 File이나 SCM과 연동하여 저장소 File의 내용을 Redmine에서 표시할 때 사용할 Encoding을 설정합니다.

한글을 제대로 표시하기 위해서 여기에 UTF-8,EUC-KR을 입력하고 저장을 누릅니다.

Redmine - Settings (Authentication required)

만약, 인증된 일부의 사용자만 Redmine을 사용할 수 있도록 설정하기 원한다면 인증 Tab에서 인증이 필요함을 Check하고 저장을 누르면 됩니다.

4. Redmine의 Project와 Subversion 저장소 연동하기

Redmine의 장점은 SCM과 Project 관리 System을 연동해서 사용할 수 있다는 것입니다. Project 저장소의 Code를 확인하거나 Revision간의 차이점을 확인할 수도 있으며, Redmine 내의 Wiki나 Issue에서 SCM의 Source를 참조할 수도 있습니다.

Redmine의 Project와 여러 SCM(SVN, CVS, Git, Mercurial, Bazzar, Darcs)을 연동할 수 있지만, 여기서는 그 중 하나인 Subversion과 연동하는 방법을 알아보도록 하겠습니다.

4.1. Subversion 저장소를 따로 운영할 경우

Subversion 저장소와 Redmine Server를 따로 운영할 경우에는 먼저 Subversion 저장소를 구성해야 합니다. Subversion 저장소를 구성하는 방법은 Ubuntu Natty Narwhal 11.04에서 Subversion Server 구성하기 Post를 참고하기 바랍니다.

Subversion 저장소와 연동하는 Redmine Server에서도 내부적으로 Subversion을 사용하기 때문에 Subversion을 설치해야 합니다. 다음과 같이 Terminal에서 입력합니다.

Redmine - Settings (SCM)

Subversion이 설치되었다면 Redmine에 Admin으로 접속한 다음, 관리 -> 설정 -> 저장소에서 위와 같이 Subversion이 Check되어 있는지 확인합니다.

Redmine - Project Settings (Repository)

Subversion 저장소와 연동할 Redmine의 Project에서 설정 -> 저장소를 누른 다음, 형상관리시스템에 Subversion을 선택합니다.

URL에는 접근할 Subversion Project 저장소의 URL을 입력합니다. file, http, https, svn, svn+ssh와 같은 Protocol을 지원하지만 Subversion 저장소가 다른 관계로 http, https, svn만 사용할 수 있습니다. (svn+ssh는 억지로 가능하게 하는 방법이 있지만 그 방법에 실용성은 의문입니다.)

로그인과 비밀번호에는 Subversion Project 저장소에 접근하기 위한 ID와 Password를 입력하고 만들기를 누릅니다.

Redmine - Project Repository

Subversion 저장소가 정상적으로 연동되면 위와 같은 화면이 표시됩니다.

4.2. Subversion 저장소와 Redmine을 동일한 Server에서 운영할 경우

Subversion 저장소와 Redmine Server를 따로 운영하는 것보다는 동일한 Server에서 운영하는 것이 더 유용합니다.

동일 Server를 사용할 경우, Redmine의 인증을 사용하여 Subversion Project 저장소에 접근할 수 있는 사용자를 관리할 수 있습니다. 또한 Redmine에서 Project를 생성하면 Project를 위한 Subversion Project 저장소를 자동으로 만들도록 설정할 수도 있습니다.

4.2.1. Subversion 저장소를 Redmine과 통합하기

먼저, Subversion을 설치하고 Subversion을 위한 저장소를 만들어야 합니다. Ubuntu Natty Narwhal 11.04에서 Subversion Server 구성하기의 1. Subversion설치를 참고하기 바랍니다.

그 다음, Subversion을 http Protocol로 접근하기 위해서 다음과 같은 Package를 설치합니다.

그리고 Redmine의 인증에 접근하기 위한 Perl Script를 Link하고 Perl의 CPAN을 사용하여 Digest::SHA1 Module을 설치합니다.

perl 명령 실행 시에 CPAN 설정을 위해 나오는 질문이 표시된다면 그냥 Enter를 누르면 됩니다.

그 다음, Subversion과 Apache를 연동하기 위해서 Terminal에서 다음과 같이 입력합니다.

위의 내용에서 상황에 맞게 수정해야 할 부분은 다음과 같습니다.

• Line 17: Allow from 다음에 http Protocol로 Subversion 저장소에 Read-only 접근을 허용할 Client의 IP를 적어줍니다. (Redmine Server의 IP를 적어주면 됨.)
• Line 29: RedmineDbPass의 따옴표 안에 Redmine 설치 시에 입력했던 MySQL redmine 계정의 비밀번호를 입력합니다.

위의 내용은 설치 시에 dbconfig-common을 사용하여 Database를 설정한 경우에만 적용됩니다. Redmine을 수동으로 설치하거나 dbconfig-common을 사용하지 않았다면 RedmineDSN, RedmineDbUser는 다를 수 있습니다.

저장했다면 다음과 같이 입력하여 Apache에 적용합니다.

마지막으로 설정이 제대로 적용되었는지 확인하기 위해서 Terminal에서 다음과 같이 입력합니다.

위의 명령은 Test의 Project 저장소를 Subversion 저장소에 만들고 http Protocol로 접근이 가능한지 확인하는 것입니다.

새로 만들어진 Project 저장소에 접근하기 위한 URL은 다음과 같습니다.

위와 같이 svn ls를 통해 암호 입력하는 Prompt가 표시되면 정상적으로 설정이 된 것입니다. 아직 어떠한 암호로도 접근이 불가능할텐데 그 이유는 다음 항목에서 설명합니다.

4.2.2. Redmine에서 Subversion Project 저장소를 생성하기

Redmine의 Project를 위한 Project 저장소를 생성하기 위해서는 Redmine SCM Plugin을 설치해야 합니다.

다음 URL에서 최신 Version의 Plugin을 Download합니다.

• Download: http://projects.andriylesyuk.com/projects/scm-creator/files

Download한 Plugin을 설치하기 위해서 다음과 같이 입력합니다.

그 다음, Plugin을 위한 설정 File을 편집하기 위해서 Terminal에서 다음과 같이 입력합니다.

위의 내용은 Subversion을 위한 설정만 적용한 것입니다. path에는 Subversion 저장소의 Directory Path, url에는 http를 통해 접근하기 위한 URL을 입력합니다.

그리고 auto_create를 true로 설정하면 Redmine에서 Project를 생성할 때 Project에 대한 Subversion Project 저장소가 자동으로 생성됩니다. (Redmien의 Project 생성 Form에서 자동으로 생성할 SCM을 선택할 수 있음.)

만약 다른 SCM을 사용하기 위해 Plugin을 설정하기 원한다면 Plugin Homepage의 Wiki를 참고하기 바랍니다.

저장한 다음, 설정을 적용하기 위해서 Apache를 다시 시작합니다.

Redmine - Plugins

Plugin이 제대로 설치되었다면 Redmine의 Admin 계정으로 접속했을 때, 관리 -> 플러그인에서 위와 같이 SCM Creator가 표시될 것입니다.

Redmine - Project Settings (Repository)

Redmine에서 Project를 생성한 후, 설정 -> 저장소에서 Subversion을 선택하면 위와 같이 Create new repository Button이 표시됩니다. 먼저 Create new repository를 눌러 Project 저장소를 생성하면, 위와 같이 file Protocol의 URL이 입력됩니다. 그 다음, 만들기(저장)를 누릅니다.

물론 다른 Subversion Server의 Project 저장소를 연결하려면 Create new repository를 누르지 않으면 됩니다. 그리고 기본으로 설정된 URL을 변경하고 Create new repository를 누르면 Project 저장소에 접근하기 위해 Redmine 인증을 사용할 수 없으니 주의하기 바랍니다.

Redmine - Saved Project Settings (Repository)

Project 저장소가 제대로 생성되었다면 위의 그림과 같이 URL을 수정할 수 없게 변경되면서 아래에 Project 저장소에 접근하기 위한 URL이 표시됩니다.

URL은 Redmine의 설정 때문에 실제 URL과 다르게 표시될 수 있습니다. 실제 접속하기 위한 URL은 다음과 같습니다.

여기서 Project의 식별자는 Project를 생성할 때 입력하는 식별자를 의미합니다. 위 그림과 같은 예일 경우 URL은 http://localhost/svn/hello가 됩니다.

Server에 생성된 Project 저장소의 Directory Path는 다음과 같습니다.

Redmine - Project Repository

정상적으로 Project 저장소가 생성되었다면, 저장소 Tab은 위의 그림과 같을 것입니다.

Redmine - Project Settings (Members)

이전 항목에서도 잠깐 이야기 했지만, 생성된 Project 저장소에 접근하기 위해서는 Redmine의 인증을 사용합니다. 때문에 Project 저장소에 접근을 허용할 User를 지정하기 위해서 Redmine의 Project에서 설정 -> 담당자를 Click합니다.

위의 화면에서 담당자를 선택한 다음, 역할을 관리자 또는 개발자로 설정하여 추가하면 해당 사용자의 ID와 Password를 사용하여 Project 저장소에 접근할 수 있습니다.

담당자를 추가했다면 Test를 위해 다음과 같이 Terminal에서 입력합니다. (생성한 Project의 식별자가 hello이고, 사용자 ID가 foo인 경우의 예)

위와 같이 정상적으로 접근이 가능하면 연동이 완료된 것입니다. 한가지 유의할 점은 이렇게 생성된 Project 저장소는 연동한 Redmine의 Project를 삭제할 때 같이 삭제된다는 것입니다.

Redmine SCM Creator Plugin에 대한 더 자세한 내용은 Plugin Page의 Wiki를 참고하기 바랍니다.

5. Gantt Chart를 PNG로 Export하기

Redmine에 입력한 일감은 Gantt Chart를 통해 한 눈에 일정을 확인할 수 있습니다. Redmine은 Gantt Chart를 PDF와 PNG로 Export할 수 있습니다. 하지만 PNG Export의 경우는 따로 Package를 설치해야 합니다.

Terminal에서 다음과 같이 입력합니다.

Redmine - Information (RMagick available)

Redmine의 admin 계정으로 접속한 다음, 관리 -> 정보에서 위와 같이 RMagic 사용 가능 (선택적)이 Check 표시로 나타난다면 정상적으로 설치된 것입니다.

Redmine - Project (Gantt Chart)

Gantt Chart를 Export할 Project에서 Gantt 챠트 Page 밑에 PNG를 Click하면 PNG로 Export된 Image를 얻을 수 있습니다.

5.1. PNG의 한글이 ?로 표시될 경우

Gantt Chart - PNG Export (before)

일감에 한글이 포함되어 있다면 위의 그림과 같이 한글이 ?로 표시될 것입니다. 이것은 Redmine에서 RMagick으로 Image를 만들 때 Font 설정 때문에 발생하는 문제인데, Google 검색으로 이것을 해결한 Post를 찾을 수 있었습니다.

하지만 해당 Post의 내용은 Windows에서 Bitnami Stack으로 Redmine을 설치한 경우이기 때문에, Ubuntu에서 PPA를 사용하여 Redmine을 설치한 경우를 위해 Post의 내용을 참조하여 Patch를 만들어 봤습니다.

• Download (for Redmine 1.3.0): rmagick_font-1.3.0.patch
• Download (for Redmine 1.3.2, 1.3.3): rmagick_font-1.3.2.patch

Redmine을 새로 설치한 경우나 Update한 경우에는 Patch를 다시 적용해야 합니다. 또한 설치된 Redmine과 Patch가 Version이 서로 맞지 않는다면 Patch 시에 문제가 발생할 수 있습니다.

Download한 Patch를 설치된 Redmine Source에 적용하기 위해서 다음과 같이 Terminal에서 입력합니다.

Redmine - Settings (RMagick Font)

Redmine에 admin 계정으로 접속한 다음, 관리 -> 설정 -> 표시방식을 Click하면 RMagic 글꼴(PNG Export) 설정이 새로 표시되는 것을 확인할 수 있습니다.

RMagick 글꼴에 한글이 제대로 표현되는 Font를 선택한 다음 저장을 누릅니다. 여기서 Font는 Redmine Server에 설치된 Font의 List가 표시됩니다.

만약, 원하는 Font를 설치하고 싶다면 /usr/share/fonts/truetype에 Font를 복사하거나 나눔글꼴과 같은 Font Package를 설치하면 됩니다.

Gantt Chart - PNG Export (after)

설정을 저장했다면 Project의 Gantt 챠트에서 PNG로 Export해 봅시다. Font를 제대로 설정했다면 위의 그림과 같이 한글이 제대로 표시되는 것을 확인할 수 있습니다.

6. Backup & Restore

Redmine 내에 첨부된 File들과 DB에 저장된 내용을 Backup 해 두면, 새로 System을 구축하거나 Server를 옮길 때에 손쉽게 Redmine을 복구할 수 있습니다.

Redmine에서 기본적으로 Backup Program을 지원하지 않기 때문에, Local에 Backup File을 저장하는 Script를 간단하게 만들어 보았습니다.

• Download: redmine_bak

Backup Script는 Redmine 1.2.x ~ 1.3.2에서 Test 되었습니다. 위에 설명한 것과 같이 PPA로 Redmine을 설치하고, dbconfig-common을 통해 DB를 설정한 경우에만 제대로 동작합니다. 이 외에 Version에서도 충분히 실행은 가능하나 Test를 하지 못했기 때문에 Backup의 안정성을 보장할 수 없음을 참고하기 바랍니다.

Download한 Backup Script를 설치하기 위해서 다음과 같이 Terminal에서 입력합니다.

6.1. Backup

Redmine의 Data를 Backup 하기 위해서는 -b Option을 사용합니다. Option 뒤에 반드시 Backup File을 저장할 Directory Path를 적어야 합니다. (/backup/redmine에 Backup File을 저장하는 예)

위의 명령을 통해 Backup한 File은 redmine-년-월-일.tar.gz의 이름을 가집니다.

Cron을 사용하여 일정한 시간에 Backup Script를 실행하도록 만들수도 있습니다. 다음은 매일 새벽 5:00에 /backup/redmine에 Backup을 저장하는 예입니다.

6.2. Restore

Backup File의 내용을 복구하려면 Redmine이 설치되지 않은 깨끗한 System에서 복구를 수행해야 합니다. 만약 설치되어 있는 상태에서 Backup File로 복구할 경우 이전의 내용은 모두 삭제됩니다.

깨끗한 System에 Redmine을 설치한 후, Subversion Server와 Redmine이 동일한 Server에 위치했었다면 Subversion과 Apache를 연동합니다. 그리고 Plugin과 Patch를 설치한 것이 있다면 그대로 설치합니다.

그 다음 Backup Script를 설치한 후, Backup File의 내용을 Redmine에 적용하기 위해서 -r Option을 사용하여 복구합니다. (Backup File인 /backup/redmine/redmine-2012-02-01.tar.gz를 가지고 복구하는 예)

Subversion과 Redmine을 동일 Server에서 운영할 경우, Subversion 저장소는 Redmine Backup Script로 Backup 되지 않습니다. Backup을 원한다면, /home/svn Directory를 압축해서 저장했다가 복구 시에 동일한 Directory에 압축을 풀어주면 됩니다.

5. 유용한 Front-end

Valgrind를 사용해서 Terminal에서 Memory Leak을 검사하는 방법을 알아봤지만, 아무래도 좀 더 보기 편리하고 사용하기 쉬운 쪽이 생산성이 좋을 것입니다. 그래서 이번에는 Valgrind를 위한 유용한 Front-end를 소개하려 합니다.

5.1. Alleyoop Memory Checker

Alleyoop은 GTK+ 기반으로 만들어진 GUI Front-end입니다. 이 Program은 Valgrind의 Memcheck Tool의 결과를 좀 더 보기 쉽게 표현해 주고 해당 Code를 쉽게 확인할 수 있습니다.

먼저 설치를 위해서 Terminal에서 다음과 같이 입력합니다.

위에서 작성한 Test Program을 가지고 Alleyoop을 사용해서 Memory Leak을 검사해 봅시다. Terminal에서 다음과 같이 입력합니다. (아래의 예는 Source의 Directory가 ~/test, 실행 File이 ./test일 경우)

-R Option을 사용하면 해당 Directory 내에서 Memory Leak이 발생한 Source Code를 찾게 됩니다. 만약 Memory Leak을 검사할 Program이 Argument(명령행 인자)를 가지고 있다면, 위의 명령에서 검사할 Program 뒤에 그대로 이어서 적으면 됩니다.

Alleyoop - Preferences

실행한 다음, 설정 -> 기본 설정에서 Memory Leak을 검사하기 위한 설정을 해야 합니다. 위의 그림과 같이 Memcheck Tab에서 Leak Check를 full로, Leak Resolution을 high로 설정하고 OK를 누릅니다.

Alleyoop - Run

그 다음 상단 Toolbar의 Run을 누르면 Program이 실행됩니다. Test Program이 종료된 후에는 위의 그림과 같이 Valgrind의 Memcheck Tool을 통해 얻은 정보가 아래의 Treeview에 표시됩니다.

Memory Leak이 발생한 경우에는 위의 그림과 같이 해당 Source의 일부분과 발생한 Line을 표시해 주기 때문에 쉽게 문제가 발생한 부분을 확인할 수 있습니다.

Gedit

그리고 Memory Leak을 나타내는 Code를 Double-Click하면 문제가 발생한 부분을 쉽게 편집할 수 있도록 Gedit가 실행되면서 해당 Source에서 Memory Leak이 발생한 Line에 Cursor를 위치시켜 줍니다.

이외에도 Alleyoop을 사용하면 NCURSES(Console 화면 출력을 쉽게 다루기 위한 Library)를 사용한 Console Program도 쉽게 Memory Leak을 검사할 수 있습니다.

NCURSES를 사용한 Program의 경우, Alleyoop에서 Run을 누르면 Alleyoop을 실행한 Terminal에서 Program이 실행되며 Program이 종료되면 결과가 Alleyoop에 표시되게 됩니다.

5.2. KCachegrind

KCachegrind는 정확하게 말하면 Memory Leak을 검사하기 위한 Front-end는 아닙니다. 하지만, Program의 Performance 향상을 위해 사용되는 상당히 좋은 Tool로 Valgrind에 대해서 설명하는 이 Post에서 잠깐 다뤄보려 합니다.

KCachegrind는 Valgrind의 도구 중 하나인 Callgrind가 생성한 Profile Data를 시각화하여 보여주는 Tool입니다.

이 Program을 사용하면 AQTime 방식과 유사하게 Callgrind로 분석한 ASCII Data를 보기 편리하게 GUI를 통해 시각화하여 보여줌으로서 사용자에게 편의를 제공합니다. 또한 이 것을 통해서 각 Function 별 Cost(비용)와 호출 관계등을 알 수 있습니다.

먼저, 설치를 위해서 Terminal에서 다음과 같이 입력합니다.

설치가 완료되었다면 이제 KCachegrind를 사용하기 위한 Profile Data를 얻어봅시다.

다음과 같이 Terminal에서 입력하여 Test할 Application의 Data를 얻습니다. (아래는 이전에 작성한 test Program의 예)

Callgrind도 마찬가지로 Runtime에 수행이 되기 때문에 Program 실행 시에 수행되지 않은 Function에 대한 Data를 얻지 못하는 것을 유의해야 합니다.

실행이 완료되면 Callgrind를 통해서 얻은 Data는 Console에 표시되는 것이 아니라 File(일반적인 경우 callgrind.out.*)로 저장됩니다.

Unity - KCachegrind

이제 Data도 얻었으니 분석을 위해서 KCachegrind를 실행해 봅시다. Unity Dash에서 개발자 도구를 선택한 다음, KCachegrind를 Click합니다.

KCachegrind

KCachegrind를 실행한 화면입니다. 일부 한글로 번역이 되어있으나 완전치는 않습니다.

분석한 Data를 Load하기 위해서 위의 그림과 같이 Toolbar의 열기를 누릅니다.

Select Callgrind Profile Data

Dialog에서 Callgrind Data가 생성된 Directory로 이동한 다음 Data File을 선택하고 열기를 누릅니다.

만약 Data의 이름을 다른 것으로 변경했다면 아래의 Filter에서 Callgrind Profile Data 대신 All Files를 선택하여 모든 File이 List에 표시되도록 변경한 후 선택하면 됩니다.

KCachegrind - Callee Map and Call Graph

Data를 제대로 Load했다면 위의 그림과 같이 표시될 것입니다.

분석을 위해서 간단하게 설명하면, 왼쪽 위의 최고비용 호출 스택은 Program 수행 시에 Cost가 가장 많이 발생한 Function의 순서대로 List에 표시합니다.
(Ir은 CPU에서 계산을 위해 Memory에서 Instruction을 가져오는 것을 나타내는 Instruction Fetch의 Cost(%)를, 호출은 호출 횟수를 나타냅니다.)

그리고 왼쪽 아래의 균일한 프로파일은 Runtime에 수행된 거의 모든 Function(Cost가 너무 낮은 것은 제외됨)의 Cost(%)와 호출 횟수를 표시합니다.
(포함은 각 Function 내에서 호출된 다른 Function의 Cost(%)까지를 포함한 값입니다. 그리고 Self는 호출된 다른 Function을 제외한 Function 자체의 Cost(%)를 나타내며, 호출됨은 해당 Function이 호출된 횟수를 나타냅니다.)

이 외에도, 오른쪽 상단과 하단에서는 균일한 프로파일에서 선택한 Function에 대하여 다음과 같은 정보를 제공합니다.

• Callers: 해당 Function을 호출한 호출자를 List로 표시합니다.
• All Callers: 호출자 뿐만 아니라 호출자를 호출한 호출자까지 포함한 List입니다.(Recursive)
• Callee Map: Function 내부에서 호출한 다른 Function의 Cost값을 가지고 Visual한 Map을 표시합니다.
• Source Code: Function의 Source가 존재할 경우, 해당 Function의 Code를 표시하며 각 Line 별로 Cost를 표시합니다. Source가 다른 곳에 위치할 경우, 설정 -> KCachegrind 설정 -> Annotations Tab에서 Source Directory를 추가할 수 있습니다.
• Callee: Function 내부에서 호출한 다른 Function의 List입니다.
• Call Graph: 해당 Function과 호출자와 호출한 다른 Function간의 호출 관계도를 표시합니다.
• All Callees: Function 내부에서 호출한 다른 Function에서 또 다른 Function을 호출한 것까지 List로 표시합니다. (Recursive)
• Caller Map: 호출자의 Cost값을 가지고 Visual한 Map으로 표시합니다.

KCachegrind로 얻은 위와 같은 정보를 통해서 Cost가 많이 발생하거나 호출 빈도가 높은 Function에 대해서 최적화를 수행하거나 설계 구조를 변경함으로서 Application의 Performance 향상을 꾀할 수 있을 것입니다.

KCachegrind의 자세한 기능및 분석 방법을 알고 싶다면 KCachegrind의 Documentation을 참고하기 바랍니다.

6. Eclipse CDT와 함께 사용하기

Eclipse CDT를 사용하여 개발하는 C/C++ Project에서도 IDE와 통합하여 쉽게 Valgrind로 Memory Leak을 검사할 수 있습니다.

Eclipse Classic 3.7.1 Indigo의 Linux version(또는 Eclipse IDE for C/C++ Linux Developers 1.4.1)을 통해 사용법을 간단하게 설명해 보도록 하겠습니다.

만약 Eclipse가 System에 설치되어 있지 않다면, Ubuntu에서 Eclipse CDT를 사용하여 Autotools Project 만들기 (Part 1)을 참고하여 설치하기 바랍니다.

Install Valgrind Tools Integration

Eclipse Classic에서 CDT를 설치한 경우라면 Valgrind를 사용하기 위한 Plugin을 설치해야 합니다. (Eclipse IDE for C/C++ Linux Devlopers를 설치했다면 이 과정은 무시해도 좋습니다.)

먼저 Help -> Install New Software를 Click하면 위와 같은 설치 Dialog가 표시됩니다.

위의 그림에서와 같이 Work with에서 Indigo를 선택하면 아래에 설치 가능한 Plugin의 List가 표시됩니다.

List에서 Linux Tools -> Valgrind Integration (Incubation)을 Check하고 Next를 눌러 설치과정을 모두 진행하면 기본적인 준비는 모두 완료됩니다.

Memory Leak Code

Memory Leak을 검사하기 위한 Source Code가 위와 같다고 가정해 봅시다.

위의 Code에서 malloc() 호출 후에 System에 반환하지 않았기 때문에 Memory Leak이 발생할 것을 알 수 있습니다.

Eclipse - Profile

이제 이 Program을 Valgrind를 통해 Memory Leak을 검사해 봅시다. Run -> Profile을 Click합니다.

Profile As

처음 Profile을 실행하게 되면 Profile As Dialog가 위와 같이 표시됩니다. 여기서 Profile With Valgrind를 선택하고 OK를 누릅니다.

Valgrind - Memcheck

아래의 Console View에 Program이 실행되면서 출력된 내용이 표시되고, Program이 종료된 이후에 Valgrind View에 Memory Leak이 발생한 내용이 표시됩니다.

Memory Leak이 발생한 내용을 Double-click하거나 Problems View에서 해당 Problem을 Double-click하면 위의 그림과 같이 Memory Leak이 발생한 Line이 선택되면서 쉽게 확인이 가능하게 됩니다.

7. 마치면서…

지금까지 Ubuntu에서 Valgrind를 사용하여 Memory Leak을 검사하는 여러가지 방법들을 알아봤습니다. Console 기반이라 쓰기 어렵다고 느껴질 수도 있지만, Front-end와 같이 사용하면 그다지 어렵게만 느껴지지 않을 것입니다.

Valgrind를 사용하여 Debugging과 Profiling을 수행함으로서, 개발하는 Application에 대한 안정성과 성능을 높이는 계기가 될 수 있기를 바랍니다.

AQTime은 Runtime 검사를 통해서 Application의 Performance를 진단하고 Memory Leak(Heap Memory를 할당했을 경우 사용 후에 System에 반환하지 않아서 발생하는 누수현상)을 검사할 수 있는 유명한 Profiling Tool입니다.

이러한 Profiling Tool을 사용하면 개발자가 미처 파악하지 못한 Application의 문제를 해결하고 Performance를 향상시킬 수 있기 때문에 Project의 안정화 시에 주로 사용됩니다.

이번 Post에서는 이와 비슷한 기능을 Linux에서 수행하는 Command-line Tool인 Valgrind를 통해서 Memory Leak을 검사하는 방법을 알아보도록 하겠습니다.

1. Valgrind?

Valgrind는 앞서 말한 대로 Linux Program의 Profiling을 위한 Application입니다. (지원하는 Platform과 Architecture를 확인하려면 여기를 방문하면 됩니다.) 그리고 License가 GPL이기 때문에 AQTime과 달리 사용하는데 전혀 비용이 들지 않습니다.

또한 수많은 Open-source Project가 Valgrind를 통해서 Debugging과 Profiling을 수행하고 있다는 것은 이 Program의 정확성과 안정성을 증명합니다.

Valgrind는 엄밀하게 말하면 Profiling Suite로 여러가지 Profiling을 위한 도구를 포함하고 있으며 각각의 도구는 valgrind 명령을 통해 통합되어 수행됩니다. 그 중 일부를 소개하면 다음과 같습니다.

• Memcheck: Memory 관리의 문제를 진단하는 Tool입니다. 할당받지 않은 Heap Memory에 접근하는 것이나 Memory Leak과 같은 문제를 이 Tool을 통하여 발견할 수 있습니다.
• Callgrind: Runtime 시에 각 함수의 호출 history와 실행 Function간의 Call Graph를 만들기 위한 정보를 기록하는데 사용하는 도구입니다. 저장된 내용은 Command-line Tool이나 KCachegrind를 통해서 분석할 수 있습니다. KCachegrind에 대해서는 이후에 간단한 사용법을 설명하겠습니다.
• Massif: Heap Memory에 대한 사용 정보를 확인할 수 있습니다. 간단한 예제와 설명은 여기를 참고하기 바랍니다.
• Helgrind: POSIX Thread(간단히 PThread)를 Program에서 사용할 때 각 Thread간의 동기화와 관련된 문제를 진단하기 위한 Tool입니다.

Valgrind는 좋은 Tool이지만 사용할 때 유의할 점이 있습니다. Valgrind는 Code 상의 오류를 검사할 수 있지만, 문맥적인 오류는 잡아내지 못합니다. 다시 말하면, 기술적으로 해당 Program이 문제가 없다는 것을 증명할 수는 있지만, 실제 그 Program이 사용자가 원하는 대로 제대로 동작한다는 것을 증명할 수 없다는 것입니다. 생각 외로 이런 Profiling Tool을 과신하는 경우가 종종 있는데 그런 점은 조심해야 합니다.

좀 더 자세한 Valgrind의 정보를 얻기 원한다면 다음 Link를 방문하기 바랍니다.

• Valgrind’s Tool Suite: http://valgrind.org/info/tools.html
• Valgrind User Manual: http://valgrind.org/docs/manual/manual.html

2. 설치

Valgrind를 설치하는 것은 간단합니다. Terminal을 새로 열어서 다음과 같이 입력하여 설치합니다.

다음 Section에서는 Test Program을 Build하면서 설명을 진행합니다. System에 Build를 위한 Package가 설치되어있지 않다면 다음과 같이 입력하여 설치합니다.

3. Memory Leak 검사하기

Valgrind가 무엇인지에 대해서 알아봤고 설치도 마쳤으니, 이제 Test Program을 만들어서 Valgrind의 Memcheck 도구를 사용하여 Memory Leak을 검사하는 방법을 알아봅시다.

Gedit나 Vim과 같은 편집기를 사용해서 다음과 같은 내용을 입력한 후 test.c라고 저장합시다.

위의 C Code를 보면 test()에서 malloc()을 통해서 Heap Memory를 할당받았지만 사용 후에 free()를 사용하여 System에 반환하지 않았기 때문에 Memory Leak이 발생하는 것을 알 수 있습니다.

이제 이 Source를 Compile해 봅시다. Terminal에서 다음과 같이 입력하여 Debugging이 가능하도록 Option을 적용하여 Compile합니다.

test.c를 Compile하여 생성된 test라는 실행 File에 대해서 이제 Valgrind를 사용하여 Memory Leak을 검사해 봅시다. Terminal에서 다음과 같이 입력하여 Valgrind를 실행합니다.

만약 Memory Leak을 검사할 Program이 Argument(명령행 인자)를 가지고 있다면, 위의 명령에서 검사할 Program 뒤에 그대로 이어서 적으면 됩니다.

위의 명령을 실행하면 먼저 test Program이 실행되고 종료된 후에 Valgrind가 검사한 정보가 Terminal에 출력됩니다.

위의 내용은 Valgrind를 실행하여 얻은 출력화면입니다. 중요한 부분은 11~14번째 Line에 있는 Memory Leak정보로, 이것은 test.c의 5번째 줄에 위치한 test()의 Code에서 Memory Leak이 발생했다는 것을 나타냅니다.

이와 같이 Memory Leak 정보에 표시된 Call Stack을 통해서 Source Code의 어느 함수의 몇번째 Line에서 Memory Leak이 발생했는지를 확인할 수 있습니다.

유의해야할 점은, Valgrind는 검사할 Program을 실행한 상태(Runtime)에서 검사하기 때문에 실행 시에 수행되지 않은 Code에 대해서는 검사할 수 없다는 것입니다. 그래서 Test Case를 잘 수행하지 않으면 Memory Leak을 검사하지 못할 수 있기 때문에 실행하기 전에 Test Case를 미리 준비하는 것이 좋습니다.

4. 마치면서…

지금까지 Valgrind를 사용하여 Memory Leak을 검사하는 방법을 간단하게 알아봤습니다. 다음 Post에서는 Valgrind의 Front-end를 사용하여 좀 더 쉽게 Memory Leak을 검사하는 방법과 Eclipse CDT로 Program을 개발했을 때 Eclipse 상에서 Valgrind를 사용하는 방법에 대해서 알아보도록 하겠습니다.

이번 Post에서는 Doxygen의 GUI Configuration Tool인 Doxywizard를 사용하여 편리하게 HTML, CHM 문서를 생성하는 방법을 설명합니다.

4. Doxywizard로 HTML 문서 만들기

Doxygen은 Command-line Tool이기 때문에 Command Interpreter(cmd.exe)를 사용하여 명령행으로 실행해야 합니다. 그리고 Doxygen을 사용하기 위해서는 Doxygen이 문서를 생성하기 위한 Configuration File이 필요합니다.

그러나 Doxygen의 Front-end인 Doxywizard를 사용하면 쉽게 Configuration File 만들 수 있고, 문서도 또한 쉽게 생성할 수 있습니다.

이번에는 가장 기본적인 문서인 HTML 문서를 생성하기 위해 Doxywizard를 사용하여 설정하는 방법과 실제 문서를 생성하는 방법을 알아봅시다.

Doxygen의 수많은 설정 Option을 설명할 수는 없기 때문에 Doxywizard를 처음 실행한 Default Option에서 꼭 필요하거나 설정하면 편리한 Option만 간단하게 설명합니다.

자세한 Option과 설명이 필요하다면 Doxygen Manual의 Reference Manual – Configuration Section을 참고하기 바랍니다.

Start Menu - Doxywizard

Doxywizard를 실행하기 위해서 시작 -> 프로그램 -> doxygen -> Doxywizard를 Click합니다.

Doxywizard - Save

Doxywizard가 위와 같이 실행되면 먼저 File -> Save를 Click하여 Doxygen Configuration을 저장할 File을 생성합니다. File의 위치는 Source Code Folder에서 문서 생성을 하위 Folder를 새로 만들어서 그 곳에 저장하는 것이 사용하기에 편리합니다.

Configuration File을 저장하면 Step 1에 Configuration File이 위치한 경로가 표시됩니다. 생성되는 HTML, CHM 문서는 이 곳에 생성됩니다. Configuration File에 Option 중 경로로를 입력해야 하는 Option이면 대부분 이 Folder에서 부터 상대경로(ex. ../Test)로 찾아가니 이점을 유의하기 바랍니다.

Step 2의 각 Tab에서는 설정을 관리하고 문서를 생성합니다. Wizard Tab으로 간단하게 설정할 수 있지만 Option이 너무 적기 때문에 Expert Tab에서 설정하는 것을 예로 들어 설명하겠습니다. (*로 표시한 것은 반드시 설정해야 합니다.)

4.1 Project Section

Doxywizard - Project

Project Section에서는 문서화하려는 대상 Project와 관련된 Option을 설정할 수 있습니다. Default 상태에서 다음과 같은 Option을 설정합니다.

• PROJECT_NAME : Project의 이름을 입력합니다. Project 이름은 나중에 생성된 HTML 문서의 최상단에 위치하게 됩니다.
• OUTPUT_LANGUAGE^* : 생성된 문서에서 사용하는 문자열에 대한 언어를 설정합니다. Korean으로 설정하면 생성된 문서에서 Doxygen이 자동으로 입력하는 문자열이 모두 한국어로 표시됩니다.
• TAB_SIZE : Source Code를 표시할 때 Tab 간격을 설정합니다. 각자 취향에 맞춰서 크기를 입력합니다.
• BUILTIN_STL_SUPPORT : Source Code에 STL를 사용할 경우(ex. std::vector) STL의 Source가 Project 내에 존재하지 않더라도 스스로 판단하여 관계를 표시합니다. STL를 상속받아서 사용하거나 Data Structure로 사용한 경우에는 Check하는 편이 좋습니다.

4.2 Build Section

Doxywizard - Build

Build Section에서는 Source Code에서 문서화를 할 요소들을 선택할 수 있습니다. 다음과 같은 Option을 취향에 맞게 설정합니다.

• EXTRACT_ALL : 상당히 세밀하게 Source Code에서 각 요소들을 분별하여 문서를 생성합니다. Private Class나 Static Member를 제외한 대부분의 요소에 대한 정보를 포함합니다. Source Code에 대한 자세한 정보를 얻기 위한다면 Check합니다.
• EXTRACT_PRIVATE : Check할 경우 Class의 Private Member도 문서에 포함됩니다.
• EXTRACT_STATIC : Check할 경우 Static Membr도 문서에 포함됩니다.
• SHOW_DIRECTORIES : Source가 여러 Folder로 되어있고 그 Folder들이 문서 생성을 위한 대상 Folder일 경우, Check하면 Folder의 구조를 생성된 문서에서 확인할 수 있습니다.

4.3 Input Section

Doxywizard - Input

Input Section은 Doxygen으로 문서를 생성할 Source Code의 위치를 지정하고 그와 관련된 Option을 설정합니다.

• INPUT^* : Doxygen으로 문서를 생성할 대상 Folder를 지정합니다. 위의 그림과 같이 오른쪽에 있는 각 Button을 통해서 개별 File이나 Directory를 추가할 수 있습니다. 추가되는 경로는 위의 Step1에 설정된 경로를 기준으로 상대경로로 입력됩니다. 물론 절대경로로도 입력할 수 있으나 추천하지는 않습니다.
• INPUT_ENCODING^* : Doxygen이 문서를 생성하기 위해 Source Code Parsing을 하기 위해서 Source Code에 대한 Encoding을 지정합니다. Borland C++ Builder 6로 생성한 Source에 한글이 들어가 있다면 CP949를 입력합니다.
• RECURSIVE^* : 위에 INPUT에 설정한 Folder의 하위 Folder가 존재하고 그 Folder에 Source Code가 존재한다면 Check하여 모두 검색하도록 합니다. Uncheck일 경우 하위 Folder를 검색하지 않습니다.

4.4 Source Browser Section

Doxywizard - Source Browser

Source Browser Section에서는 생성할 문서에 Source Code의 내용을 포함시키는 것과 관련된 Option을 설정할 수 있습니다.

• SOURCE_BROWSER : Check할 경우 생성할 문서에 Source Code의 Header 뿐만 아니라 Source의 내용이 추가되어 저장됩니다.
• INLINE_SOURCES : Check할 경우 생성할 문서에 각 Method나 Enum Type에 대한 설명 바로 밑에 해당 Code가 바로 표시됩니다.

4.5 HTML Section

Doxywizard - HTML

HTML 문서를 생성하기 위한 Option을 설정하는 Section입니다. Default 설정이 HTML 문서를 생성하게 되어있기 때문에 별로 수정할 것은 없으나 아래의 Option을 설정하면 편리합니다.

• GENERATE_TREEVIEW : Check할 경우 CHM 문서와 같이 생성된 HTML문서의 왼쪽 Frame의 전체 문서의 구조가 Treeview 형태로 표시됩니다.

4.6 LaTeX Section

Doxywizard - LaTeX

LaTeX는 문서 조판 System으로서 역사가 깊은 Program입니다. LaTex을 사용하면(System에 LaTeX이 설치되어 있는 경우) Source Code에 대한 PDF문서를 생성할 수 있지만, 여기서는 HTML문서를 생성할 것이므로 다음과 같이 설정합니다.

• GENERATE_LATEX^* : Uncheck하면 LaTeX 문서를 생성하지 않습니다.

4.7 Dot Section

Doxywizard - Dot

Dot Section에서는 Graphviz Package의 Program 중 하나인 Dot을 사용하여 Class Diagram이나 호출 관계도 등을 그리는 것에 대한 Option을 설정할 수 있습니다.

• HAVE_DOT^* : Dot이 System에 설치되어 있는지를 나타내는 Option입니다. 이전 Post에서 Graphviz를 설치했기 때문에 Check합니다.
• UML_LOOK^* : Check할 경우 Class의 상속 Diagram과 협업 Diagram을 UML에서 정의한 Style로 그립니다.

위와 같이 Option을 설정할 경우 Class의 상속 Diagram과 협업 Diagram이 아래와 같이 표시됩니다.

HTML - Class Diagram

4.8 Run

Doxywizard - Run Tab

이제 설정이 완료되었습니다. File -> Save를 Click하여 변경한 내용을 저장하고 Run Tab에서 Run doxygen Button을 Click하면 HTML문서를 생성합니다.

특별한 Error가 없다면 "Doxygen has finished"라는 Message가 표시될 것입니다. 문제가 생겼다면 설정을 다시 한번 확인해보기 바랍니다. Input Section의 INPUT Option에서 Source Code의 경로가 잘못되어 있는 것이 아니라면 대부분 제대로 생성될 것입니다.

생성된 HTML문서를 확인하기 위해서 아래의 Show HTML output Button을 Click하면 System의 기본 Browser를 통해서 생성된 HTML 문서를 확인할 수 있습니다. (생성된 문서는 Step1에 설정한 경로\html\index.html을 열어서 확인할 수도 있습니다.)

5. Doxywizard로 CHM 문서 만들기

Doxygen으로 생성한 HTML 문서는 여러 HTML과 CSS, Image 등으로 구성되어 있기 때문에 문서를 보관하거나 이동해서 가지고 다니는 용도로는 조금 부적합합니다.

Doxygen으로 생성할 수 있는 여러 문서 Type 중에서 CHM 문서를 생성하면, 하나의 File로 문서를 보관할 수 있고 또한 문서 내용을 검색할 수 있으며 굳이 문서를 읽기 위해 Viewer를 설치할 필요가 없이 Windows 환경에서 바로 열람이 가능합니다.

이번에는 Doxywizard를 사용해서 Source Code에 대한 CHM 문서를 만들어 봅시다.

5.1 HTML Help Workshop 설치

CHM은 Windows의 도움말 File(Microsoft Compiled HTML Help)의 확장자로 실제로는 HTML을 압축한 형태를 띠고 있습니다. 이 CHM 문서를 생성하기 위해서는 MS에서 제공하는 HTML Help Workshop이라는 Program을 설치해야 합니다.

HTML Help Workshop Download

HTML Help Workshop은 MS에서 무료로 배포하고 있으므로 HTML Help Workshop Page에 들어가서 위의 그림과 같이 htmlhelp.exe를 Download한 후 설치합니다.

5.2 Doxywizard 설정 (HTML Section)

Doxywizard - HTML

CHM을 생성할 때의 Doxywizard의 설정은 위의 HTML 문서를 생성할 때와 동일합니다. 다만 HTML Section에서 아래와 같은 Option을 더 설정해야 합니다.

• GENERATE_HTMLHELP^*: Check하면 CHM 문서를 생성합니다.
• CHM_FILE^*: CHM File이 저장되는 경로와 File명을 지정합니다. 유의할 것은 다른 설정과 달리 여기의 기본 Folder는 “Step1에서 지정한 Folder\html”입니다.
• HHC_LOCATION^*: HTML Help Workshop에서 CHM을 생성하는 Console Program인 hhc.exe의 경로를 지정합니다. 경로는 다음과 같습니다.
  32bit OS – C:\Program Files\HTML Help Workshop\hhc.exe
  64bit OS – C:\Program Files (x86)\HTML Help Workshop\hhc.exe
• CHM_INDEX_ENCODING^*: CHM 문서의 Index Encoding을 지정합니다. 한글이 사용된 경우 CP949를 입력합니다.

GENERATE_HTMLHELP를 Check하여 CHM 문서를 생성할 경우, HTML 문서의 왼쪽 Frame에 Treeview를 만들어 주는 GENERATE_TREEVIEW Option은 동작하지 않습니다.

5.3 Run

Doxywizard - Run

File -> Save로 설정을 저장한 다음, Run Tab에서 Run doxygen Button을 Click하면 CHM 문서가 생성됩니다. 위의 그림에 “Running html help compiler”라는 Text를 통해서 CHM 문서가 생성된다는 것을 확인할 수 있습니다.

CHM - Mainpage

만들어진 CHM 문서는 CHM_FILE Option에 설정한 경로에 해당 이름으로 생성됩니다. Double-click해서 문서를 열면 위와 같은 모습이 될 것입니다.

6. 마치면서…

이상으로 Doxygen을 사용하여 Borland C++ Builder 6로 구현한 Project를 문서화하는 방법을 알아봤습니다.

Project를 수행하는 것은 각자 개개인의 Programming 실력을 요구하지만, 또한 그것과 더불어 개발자 간의 Communication이 필요합니다. Doxygen을 이용한 문서화를 통해서 Project 구현에 대한 개발자 간의 Communication이 더 증진되기 바랍니다.

Doxygen을 사용하면 C++, C, C#, Fortran, Java, Objective-C, PHP, Python 등의 언어를 사용한 Source Code에 Doxygen에서 정의한 Style로 주석을 작성하면 자동으로 문서를 생성할 수 있게 됩니다.

생성된 문서는 마치 MSDN이나 기타 Live API Document와 같은 형식으로 Web Browser, PDF Reader, CHM Help 등으로 열람이 가능합니다. 이것은 여럿이 동시에 작업하는 Project에 더욱 유용합니다.

이번 Post에서는 Borland C++ Builder 6로 작성한 Project를 Doxygen을 사용하여 문서화하는 방법을 다루도록 하겠습니다.

1. Doxygen 설치

Doxygen 자체는 Source Code의 주석을 사용하여 문서를 자동으로 생성하는 도구로서 IDE와 통합되어 동작하지 않습니다. 다만 Doxygen에서 정의한 Style에 주석을 Project 개발시에 Source Code에 작성하면 됩니다. (Java, Flex의 경우에는 문서화 도구인 JavaDoc, ASDoc Style로 작성한 주석을 바로 Parsing하여 Eclipse에서 해당 Class나 Method에 대한 주석을 바로 확인할 수 있습니다.)

또한 Doxygen은 Cross-Platform Tool로서 Windows, Mac OS X, Linux (or Unix-like OS)에서 사용이 가능합니다. 이것은 Windows Application의 Source Code를 Doxygen에서 지정한 형식으로 주석을 작성해 놓으면, Web Server가 동작하는 다른 OS에서 Doxygen을 사용하여 Source Code 문서를 생성할 수 있다는 것을 말합니다. 한마디로 해당 Project에 대한 API Web Service(like MSDN)를 운영할 수 있게 됩니다.

이제 어느정도 설명이 끝났으니 설치를 해보도록 합시다. Doxygen의 Homepage에 접속합니다.

Doxygen Site

Program을 Download하기 위해서 오른쪽의 Download를 Click합니다.

Doxygen Download

여러 OS에 대한 Binary가 존재하는데 여기에서는 32-bit binary distribution for Windows XP/Vista/7 Section의 설치 File을 Download합니다.

Doxygen Install

Download한 설치 File을 설치합니다. 설치 중간에 위와 같이 Doxygen 구성요소가 나오는데 여기에서 Doxywizard GUI를 선택합니다.

Doxywizard를 사용하면 Command-line 기반의 Doxygen을 좀 더 편리하게 쓸 수 있습니다.

Graphviz Site

그리고 한 가지 더 설치해야 할 Tool이 있습니다. Doxygen은 문서를 생성할 때 Class나 Method의 관계를 나타내기 위해서 Graphviz라는 Tool을 사용합니다. 이번에는 Graphviz를 설치하도록 합시다.

Graphviz의 Homepage에서 왼쪽 Download를 Click합니다.

Graphiviz License Agreement

License 동의를 위해서 맨 아래쪽의 Agree를 Click합니다.

Graphviz Download

Windows – Stable and Development Windows Install Packages를 Click하여 Download한 후 설치하면 모든 준비는 완료됩니다.

2. Source Code에 문서화를 위한 Comment 작성

BCB6 - Doxygen Test Project

설치가 모두 끝났으니 이제 Source Code에 Doxygen Style의 주석을 달아봅시다. Style 및 사용하는 Metatag는 여러가지가 있는데 여기서는 간단하게 주로 사용하는 것을 Template 형태로 적어보도록 하겠습니다.

좀 더 자세한 내용을 알기 원한다면 아래의 Doxygen Manual을 참조하기 바랍니다.

• Online Manual : http://www.stack.nl/~dimitri/doxygen/download.html#latestman
• 설치된 Manual : C:\Program Files\doxygen\html\index.html
  (64bit OS일 경우에는 C:\Program Files (x86)\doxygen\html\index.html)

2.1 Class comment template

Class에 대한 주석을 작성할 때는 아래와 같이 작성하면 됩니다. 아래의 예제에서는 Class에 대한 주석 뿐만 아니라, 전역 변수, Method에 대한 주석도 설명하고 있습니다.

위와 같은 주석을 작성한 후, Doxygen으로 문서를 생성한 모습은 다음과 같습니다.

HTML - Class Description

2.2 Method comment template

Class의 Metho에 대한 주석을 작성할 때는 다음과 같이 작성하면 됩니다.

Parameter가 여러 개일 경우에는 Parameter의 순서대로 @param을 사용하여 설명을 적습니다. 개인적으로는 Debugging을 하기 위해서 header를 반복해서 살펴야 하는 Case를 가능하면 피하기 위해서 Method 주석은 header보다는 cpp에 적는 편입니다.

위와 같이 작성한 주석을 가지고 Doxygen으로 문서를 생성한 모습은 다음과 같습니다.

HTML - Method Description

2.3 Mainpage comment template

Mainpage는 Doxygen 문서의 Mainpage(index.html)를 주석으로 생성하는 것을 의미합니다. Mainpage 주석은 Source에 오직 한 군데만 작성해야 하며 이 곳은 주로 Project의 개관, 알아두어야 할 정보나 Compile 방법 등을 적어 놓는데 사용합니다.

위와 같은 Mainpage Comment를 Doxygen으로 문서화하면 다음과 같은 모습이 됩니다.

HTML - Mainpage

3. 마치면서…

이상으로 Doxygen을 설치하는 방법과 문서 생성을 위해 Source Code에 주석을 다는 방법을 알아봤습니다. 다음 Post에서는 Source Code에 작성한 주석을 Doxywizard를 사용해서 HTML과 CHM 문서로 만드는 방법을 알아보도록 하겠습니다.