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 문서로 만드는 방법을 알아보도록 하겠습니다.

• Ubuntu Oneiric Ocelot 11.10에서 Test 완료 (2012-01-05)

“Nautilus에서 Source Code를 Subversion으로 관리하자 : RabbitVCS”의 마지막 Post로 이전 Part 1, Part 2에 이어서 Branch/Tag, Merge에 대해서 설명하도록 하겠습니다. 예제를 가지고 설명하기 때문에 이전 Post를 간단하게 읽어보기를 권합니다.

14. Branch/Tag

Project를 진행하다가 새로운 기능을 추가하기 위해서 Test를 위한 Project를 만들어야 할 때가 있습니다. Pilot Project로 Test하는 경우도 있지만 현재 Project Source를 가지고 Test하면서 그 Code를 Subversion으로 관리하는 경우가 대부분일 것입니다.

이럴 때 사용하는 것이 Branch라는 기능입니다. Branch는 사실 기능이 아니라 개념으로써, 설명한 것과 같이 Project의 새 기능 추가 Test 등의 이유로 현재 Project 저장소에 있는 Code를 그대로 복제하여 새로운 곁가지 Project를 만드는 것을 의미합니다.

Branch Project를 통해서 새 기능을 추가하거나 Test한다고 하더라도 Trunk에 존재하는 최신 Source에 대해서는 영향이 미치지 않으며 나중에 Branch에 있는 Code를 Trunk에 통합할 수도 있습니다.

Hello Project의 Branch를 만들어 보면서 그 기능을 간단히 알아봅시다.

RabbitVCS - Branch

Hello Project Folder 내의 Branches Folder에서 Mouse 오른쪽 Button Popup을 띄운 후, RabbitVCS -> Branch/Tag를 Click합니다.

Branch/Tag Dialog

Branch/Tag Dialog에서는 다음과 같은 내용을 설정할 수 있습니다. (위의 그림은 Hello Project의 trunk를 branches/hello-dev로 Branch 하는 경우를 나타냄)

• Repository : From – Source를 가져올 Project 저장소를 나타냅니다. To – 가져온 Source를 저장할 Directory를 설정합니다.
• Create copy from : Source를 Project 저장소에서 가져올 때 어느 Source를 가져올 지를 결정하는 것으로 HEAD를 선택하면 최신을, Number를 선택하면 원하는 Revision을 가져올 수 있습니다.
• Add message : Branch에 대한 Log Message를 입력합니다.

Completed branch

Branch/Tag Dialog에서 설정한 후 확인을 누르면, 위의 그림과 같이 Hello Project의 Branch인 hello-dev가 생성됩니다.

Branched hello

Hello Project의 branches/hello-dev Folder안에 현재 trunk의 최신 Source인 test.c가 존재하는 것을 확인할 수 있습니다. 이제 Branch가 완료되었으니 hello-dev에서 새 기능을 위한 Code를 작성하면 됩니다.

RabbitVCS - Tag

이번에는 Tag에 대해서 알아보도록 하겠습니다. Project가 어느 정도 안정화 되어 Version Up을 할 경우 이것을 배포하거나 따로 Source를 관리할 필요가 생기게 됩니다. 이럴 때 사용하는 것이 Tag 기능으로 간단하게 현재 trunk의 Source를 복제하여 Project의 Tag Folder 안에 관리하는 것을 의미합니다.

Tag를 사용하기 위해서는 Branch와 동일하게 Project의 tags Folder 안에서 Mouse 오른쪽 Button Popup을 띄운 후, RabbitVCS -> Branch/Tag를 Click합니다.

Branch/Tag Dialog

Branch/Tag Dialog에서 Tag를 위해서는 Repository의 To에 대한 경로를 Project tags Folder내에 경로로 지정해 주면 됩니다. (위의 그림은 trunk의 현재 최신 Source를 tags/hello-1.0으로 복제하는 경우를 나타냄)

Completed tag

Tag가 완료되면 hello-1.0이 tags Folder 안에 생성됩니다.

Tagged hello

Tag 완료 후, tags/hello-1.0의 모습입니다.

Commit branch and tag

Branch와 Tag가 완료되었지만 여기서 끝난 것은 아닙니다. Project 저장소에는 Branch/Tag를 한 Source가 아직 등록되지 않았기 때문에 생성된 Folder를 Project 저장소에 등록하기 위해 반드시 Commit을 해야 합니다.

위의 그림은 Commit Dialog의 예로 Branch를 통해 hello-dev가, Tag를 통해 hello-1.0이 생성된 것을 Commit하는 모습입니다. Commit이 완료되면 Branch와 Tag로 생성된 Directory가 Project 저장소에 적용됩니다.

15. Merge

위에서 알아봤던 Branch 기능으로 새 Branch를 만들어 새 기능의 개발을 끝내게 되었다면, 이제 원래 Source Tree에 합쳐서 새 기능이 적용되도록 만들어야 할 것입니다. 이 경우에 사용하는 것이 바로 Merge 기능입니다.

이전에 Branch로 만들었던 hello-dev를 가지고 Merge 기능에 대해서 알아봅시다.

branches/hello-dev/test.c를 다음과 같이 Postfix 연산을 Function으로 따로 만들어 저장합시다.

RabbitVCS - Commit branched source

Commit Dialog

이제 저장된 branches/hello-dev/test.c를 Commit하여 Project 저장소에 적용시킵니다.

RabbitVCS - Merge

이제 hello-dev와 trunk의 현재 Source를 합쳐보도록 하겠습니다. trunk Folder를 선택한 다음, Mouse 오른쪽 Button Popup에서 RabbitVCS -> Merge를 Click합니다.

Merge Type

Merge 과정을 위한 Dialog가 표시됩니다. Step1 에서는 Merge Type을 선택할 수 있는데 각 Type은 다음과 같습니다.

• Merge a range of revisions : 대상 Folder에 하나의 Source Tree를 병합합니다. 1개의 branch에서 원하는 revision의 변경부분만 대상 Folder에 통합할 수도 있습니다.
• Merge two differenct trees : 대상 Folder에 2개의 다른 Source Tree를 병합합니다. 2개의 branch의 내용을 병합하기 위해서 사용합니다.

여기에서는 1개의 branch를 병합하는 것이므로 Merge a range of revisions를 선택하고 앞으로를 누릅니다.

Merge a range of revisions

Step 2에서는 합칠 branch의 정보를 입력합니다. 각 Field에는 다음을 입력합니다.

• URL to merge from : 대상 Folder에 통합할 Branch의 Project 저장소 URL을 입력합니다.
• Revision Range : 통합할 Branch에서 선택한 Revision만을 대상 Folder에 적용할 수 있습니다. comma(,)로 여러개를 입력할 수 있고, dash(-)는 범위를 나타냅니다. 옆의 돋보기 Icon을 Click하면 Commit Log를 통해서 원하는 Revision을 선택할 수 있도록 도와줍니다.
  

  Revision Log

대부분의 경우 Branch가 된 시점에서 부터 최신 Revision까지를 적용하게 됩니다. Commit Log를 보니 Revision 6에서 branch가 되었기 때문에 Revision Range에 6-HEAD(Revision 6에서 최신 Revision까지)를 입력해서 병합해 봅시다. 모두 입력했다면 앞으로를 누릅니다.

Final Options

Step3에서는 Option을 설정할 수 있습니다. Recursive(하위 Folder까지 병합)는 반드시 선택합니다. Test Merge를 눌러서 Merge 설정이 제대로 되었는지 그리고 병합시 문제가 없는지를 Test해 봅시다.

Merge Dry Test

Test Merge가 제대로 수행이 되었다면 위와 같이 merge_completed Message가 표시될 것입니다. 이상이 없다면 확인을 누른 후, Merge Dialog에서 적용을 누릅니다.

Merge Complete

Test Merge가 성공적으로 끝났기 때문에 Merge도 위와 같이 정상적으로 이루어질 것입니다.

Nautilus - Merged trunk folder

Nautilus에서 병합된 trunk Folder를 확인해봤습니다. 저의 경우는 branch된 이후로 trunk의 Source가 변경되었기 때문에 Conflict가 발생했네요. 생성된 각 File은 다음과 같은 의미를 갖고 있습니다.

• test.c.merge-left.r6 : Merge Dialog에서 입력했던 Revision Range의 시작 Revision의 Source입니다.
• test.c.merge-right.r15 : Merge Dialog에서 입력했던 Revision Range의 끝 Revision의 Source입니다.
• test.c.working : 병합되기 전 대상 Folder에 존재한 Source입니다.

Merge로 일어난 Conflict는 Update로 발생한 Conflict와 마찬가지로 해당 Source(여기서는 test.c)를 수정한 다음, Resolve 기능을 사용하면 문제가 해결됩니다.

Commit Dialog

Merge가 완료되었다면 Project 저장소에 적용하기 위해 Commit을 실행합니다. Commit까지 정상적으로 완료되었다면 Merge에 대한 모든 과정이 끝나게 됩니다.

16. GEdit – RabbitVCS Plugin

Gedit - RabbitVCS Plugin

마지막으로 Gedit를 위한 RabbitVCS Plugin을 소개합니다. RabbitVCS Plugin을 설치하면 Subversion으로 관리되는 Source를 Gedit로 편집할 경우 Gedit 상에서 RabbitVCS의 기능을 편리하게 사용할 수 있습니다.

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

Gedit - Preferences

설치된 RabbitVCS Plugin을 사용하기 위해서는 Gedit를 실행한 다음, 편집 -> 기본 설정 -> 플러그인 Tab에서 RabbitVCS를 Check한 후 닫기를 누르면 됩니다.

17. 마치면서…

이상으로 RabbitVCS를 설치하는 방법과 각 기능에 대해서 간단하게 알아보았습니다.

Source Code를 Subversion으로 관리할 때 IDE에서 제공하는 기능을 주로 사용함과 동시에 Nautilus에서 편하게 관리할 수 있는 RabbitVCS를 사용한다면 좀 더 편리하게 Source를 관리할 수 있을 것이라 생각합니다.

그럼 즐거운 Programming 생활(?)이 되시길..