1. Intro
학교나 직장에서 프로젝트를 진행 하다보면, 여러명이 동시에 하나의 프로젝트를 맡아 함께 작업을 하기 마련입니다. 프로젝트를 진행 하면서 소스 코드를 작성 하는 것도 중요한 일이지만 할당된 시간의 대부분을 문서화 작업에 소비 하게 됩니다. 만약 규모가 작아서 혼자서 프로그램을 만든다고 해도, 나중에 인수인계를 한다거나 시간이 지난 후에 유지 보수, 업그레이드 등의 작업을 하기 위해서 다시 소스 파일들을 보게 될때, 잘 작성된 문서가 없다면 시간적이나, 금전적으로도 엄청난 손실이 아닐 수 없습니다. 프로젝트 관련 문서도 많은 종류가 있습니다만, 여기서는 소스 코드에 대한 문서화에 대해서 다루기로 합니다. 소스 코드에 주석을 적는 것은 너무나 당연한 일이고 모든 프로그래머들이 그렇게 하고 있을 것입니다. 주석은 기본적으로 코드를 잘 이해하고, 나중에 다시 봤을 때에도 쉽게 기억해 낼 수 있도록 해주는데에 기본적인 목적이 있습니다. 다른 사람이 작성한 코드를 보게 되거나, 다른사람이 자신의 코드를 보게 될 수도 있으며, 이러한 일들은 공동으로 진행하는 프로젝트에서 흔하게 일어나게 됩니다. 여기서 한가지 문제가 발생합니다. 주석을 훌륭하게 작성을 해놓았다고 해도 소스 코드가 길어지거나, 파일 수가 많은 경우에는 참조하기가 힘들어 질 것이고 동료들간의 의사소통에 걸리는 시간도 증가 할 것입니다. 이러한 문제를 해결하기 위해서라도 소스 코드 문서화는 반드시 필요합니다.
소스 코드의 주석을 이용해 코드 문서화를 자동으로 해주는 doxygen에 대해서 알아 보겠습니다.
2. Doxygen 이란 무엇인가?
doxygen은 C++,C,JAVA,Objective-C, IDL, PHP,C#, D 와 같은 프로그래밍 언어를 위한 문서화 시스템입니다.
doxygen은 문서화된 소스파일로 부터 HTML, LaTeX 포맷의 문서를 생성시켜 줍니다. 또한 rtf, PostScript, Hyperlinked PDF, Compressed HTML, Unix Man page 등의 자주 볼 수 있는 문서 포맷으로도 생성이 가능합니다. 문서화 작업은 소스 코드로부터 직접 추출이 되는데, 이러한 특징으로 소스코드의 문서화를 훨씬 손쉽게 작성하고 유지,관리 할 수 있습니다.
doxygen을 이용해서 문서화 되지 않은 소스들의 구조를 알아 볼 수 있는데, 이 기능은 특히 대규모로 산재해 있는 소스 코드들의 구조를 빠르게 이해할 수 있게 해주는 대단히 유용한 기능입니다.
또한, 다양한 요소들의 관계를 구체적으로 나타낼 수 있습니다. 의존 관계, 상속 관계, UML을 위한 Collaboration 다이어그램 등을 그림으로 표시를 해주기 때문에, 한눈에 전체적인 구조를 파악 할 수 있도록 해줍니다.
심지어 doxygen을 이용해서 일반적인 문서 자체를 만드는 일도 가능합니다. (doxygen 메뉴얼을 보면 PDF 포맷인데, doxygen 자체를 이용하여 생성했다고 제작자가 밝혀 놓았군요 :))
doxygen은 Linux 와 Mac OS X에서 개발 되었지만, 대부분의 UNIX 계열과, Windows 계열도 지원합니다.
이 문서에서는 Linux 에서 사용하는 방법을 알아 보겠습니다. OS에 따라서 설치 방법, 몇가지 설정 방법만 다를뿐 doxygen 자체의 사용방법,기능등은 똑같습니다.
3. Doxygen 설치
소스 설치
doxygen은 앞에서도 언급했듯이 Unix, Linux, Mac OS X, Windows 등 여러가지 OS를 지원하며, 소스나 바이너리, rpm 패키지, deb 패키지 들로도
다운 받을 수 있습니다. 본인의 OS 환경과 취향에 맞는 버전을 다운로드 받으시면 됩니다.
doxygen download latest src
저의 경우 현재 최신 버전인 1.4.4 버전을 다운 받았습니다.
다운받은 소스의 압축을 풉니다.
tar xzvf doxygen-1.4.4.src.tar.gz
설정 스크립트를 실행 합니다.
cd doxygen-1.4.4
./configure
이때, 시스템에 Qt-3.2.x 버전 이상이 설치 되어있고, GUI 환경에서의 doxygen을 사용하고 싶으시면 configure 스크립트에 다음과 같이 옵션을 추가 해주시면 됩니다.
./configure –with-doxywizard
GNU make를 이용해 컴파일 하고 설치합니다.
make && make install
바이너리 설치
바이너리 버전을 다운 받으셨다면 configure 스크립트 실행 후에 make install 하시면 됩니다.
tar xzvf doxygen-1.4.4.linux.bin.tar.gz
cd doxygen-1.4.4
./configure
make install
설치 디렉토리는 기본적으로 /usr 밑이지만, conifgure 스크립트 실행시 –prefix 옵션으로 변경 가능하므로 원하는곳에 설치 하시면 됩니다.
4. Graphviz 설치
Graphviz (Graph Visualization)은 소프트웨어 엔지니어링, 데이터베이스, 웹 디자인, 네트워크, 기타 다른 여러 영역에 있어서의 시각적인 표현등을 위해서 자동으로 그래프를 그려주는 프로그램입니다. 자세한 사항이 궁금하시다면 graphviz 웹사이트를 방문해 보시길 바랍니다. 구조적인 데이터의 정보등을 아주 훌륭하게 그려냅니다. 웹사이트의 Gallery 섹션을 보시면 여러가지 샘플 이미지를 감상 하실 수 있습니다. doxygen을 사용하는데 있어서 필수로 설치 하여야 하는 프로그램은 아닙니다만, 설치 하셔도 절대 후회하지 않을 것입니다.
graphviz download page에서 약관에 동의를 하고, 소스 또는 바이너리 버전을 다운 받습니다. 배포판에 맞는 rpm 패키지도 있으니 맘에 드는 설치 버전을 다운로드 받으시길 바랍니다.
tar xzvf graphviz-2.6.tar.gz
cd graphviz-2.6
./configure
make && make install
이제, doxygen을 이용하여 프로젝트 문서화를 하는데 있어서 필요한 프로그램의 설치 과정은 모두 끝났습니다.
5. Doxygen Configuration File 생성 및 설정 방법
실제로 doxygen을 사용하기 위해서는 doxygen configuration 파일을 생성하고 설정을 해야 합니다.
doxygen은 모든 세팅을 설정 파일에서 할 수 있습니다. 프로젝트 마다 별도로 설정 파일을 두고 문서화 작업을 하는 것이 좋습니다. 설정 파일에 어떻게 설정을 하느냐에 따라서, 프로젝트의 단일 소스 파일에 대한 문서화 결과를 얻을 수도 있고, 반복되는 스캔을 통해 전체 소스 트리에 대한 문서화 결과를 얻을 수도 있습니다.
처음에는 설정 파일이 존재하지 않기 때문에 doxygen을 이용하여 설정 파일을 만들어줘야 합니다. 만드는 방법은 간단합니다. 다음과 같이 doxygen 명령 다음에 -g 옵션을 주면 됩니다.
doxygen -g 설정파일이름
예를 들어 doxygen -g test_project_doxygen_config 라고 명령을 내리면, test_project_doxygen_config 라는 doxygen 설정 파일이 생성되는 것을 볼 수 있습니다. 만일 설정 파일이름을 적지 않으면 디폴트로 ‘Doxyfile’ 이라는 이름의 파일이 생성됩니다. 또한, 이미 같은 이름의 설정 파일이 존재 하는 경우에는 doxygen이 기존에 있던 파일이름 뒤에 .bak을 붙이는 방식으로 이름을 변경해 줍니다. 설정파일의 설정 방식는 간단한 Makefile의 그것과 유사합니다. vi 에디터 등을 이용해서 생성한 설정파일을 열어보면 대부분 다음과 같은 형태로 구성되어있는 것을 알 수 있습니다.
TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 …
여기서 doxygen이 생성해준 설정 파일의 대부분의 설정항목들은 기본값으로 대부분 그대로 사용하면 됩니다. 자세한 설정은 doxygen 공식 메뉴얼을 참조 하시면 됩니다. 만약 텍스트 에디터로 설정파일을 열어 직접 수정하는게 어렵거나, 불편하다면 doxywizard를 이용하면 됩니다. doxywizard는 X윈도우 상에서 GUI 형태로 설정파일 생성 부터 시작해서 세부 항목까지 설정을 가능하게 해주고 저장한 설정 파일을 이용해서 최종 결과물까지 나오는 과정을 지켜 볼 수 있게 해주는 GUI doxygen이라고 생각하시면 됩니다. 다음은 GNOME 환경에서 실행된 doxywizard의 몇가지 화면의 모습을 캡쳐 한 것입니다.
-doxywizard 실행 초기 화면-
-wizard 버튼을 클릭한 후 output 탭을 클릭한 화면-
-wizard 버튼을 클릭한 후 diagrams 탭을 클릭한 화면-
-Experts 버튼을 클릭한 후 builds 탭을 클릭한 화면-
doxywizard에서는 doxygen으로 생성한 설정파일의 각 항목들이 여러가지 탭들과, 체크박스 등으로 선택 할 수 있게 해주기 때문에 직관적으로 설정 파일들을 수정하고 저장할 수 있습니다.
그럼, 일반적으로 많이 사용하는 설정 항목에 대해서 알아 보겠습니다. doxygen 설정 파일은 대부분이 YES 또는 NO로 세팅을 하는 방식으로 이루어져 있으며, 다른 경우라면 파일 경로등을 직접 입력하는 정도가 있습니다. 모든 설정 항목 위에 자세한 설명이 적혀 있으므로 참고 하시면 좋습니다.
PROJECT_NAME : 문서화할 프로젝트 이름을 적습니다.
ex) PROJECT_NAME = Test Project
PROJECT_NUMBER : 문서의 버전관리등을 위해서 프로젝트의 관리 번호를 입력합니다.
ex) PROJECT_NUMBER = 1.0
OUTPUT_DIRECTORY : doxygen이 만들어낼 문서화 파일들이 생성되는 디렉토리를 적어줍니다. 공백으로 둘 경우에는 현재 doxygen을 실행한 디렉토리가 기본으로 지정됩니다.
ex) OUTPUT_DIRECTORY = /home/parasite/
CREATE_SUBDIRS : 이 옵션을 YES로 세팅을 하면 OUTPUT_DIRECTORY로 부터 2단계의 하위 디렉토리들을 생성하고 생성된 디렉토리들 밑에 파일들이 생성됩니다. 하나의 디렉토리에 모든 문서화 파일들을 생성하여 파일시스템의 성능문제를 야기 시킬 수 있는데, 이 옵션을 켜서 그러한 문제를 해결하는데에 도움을 줄 수 있습니다.
ex) CREATE_SUBDIRS = YES
OUTPUT_LANGUAGE : 생성된 문서의 언어를 적습니다. 기본으로 영어를 지원하며, 많은 종류의 언어를 지원합니다. 한글을 출력하기 위해서는 Korean 또는 Korean-en 으로 설정합니다. 저의 경우는 Korean 으로 설정했으며, 한글 영어 모두 잘 나왔습니다.
ex) OUTPUT_LANGUAGE = Korean
INPUT : 소스 파일들의 위치를 입력합니다. 파일의 경우 “myfile.cpp” 와 같이 적어주면 되고, 디렉토리인 경우 “/usr/src/myproject” 와 같이 적어주면 됩니다. 디렉토리가 서로 다른 위치에 있는 경우는 공백으로 구분해서 뒤에 더 적어주면 됩니다.
ex) INPUT = /home/parasite/test_project
FILE_PATTERNS : INPUT 항목에 디렉토리를 적어준 경우 원치 않는 파일들이 문서화 되어 나타나는 경우가 생길 수 있습니다. 이때 와일드 카드 패턴(*.cpp *.h) 등으로 특정 확장자를 가진 파일들만 문서화를 수행 하도록 지정 할 수 있습니다. 이 항목을 공백으로 두면 다음의 확장자들을 가진 파일들 모두 인식하게 됩니다. *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm
ex) FILE_PATTERNS = *.h *.c
RECURSIVE : INPUT 디렉토리의 하위 디렉토리를 검색하여 문서화를 수행 할지의 여부를 결정합니다. 공백으로 둘 경우 NO로 설정됩니다.
ex) RECURSIVE = YES
EXCLUDE : INPUT 디렉토리 하위 디렉토리들 중에서 문서화를 하지 않을 파일이나 디렉토리이름을 적습니다.
ex) EXCLUDE = /home/parasite/test_project/exclude_dir
EXTRACT_ALL : 문서의 모든 객체들에 대한 문서화를 수행합니다. 단, EXTRACT_PRIVATE 와 EXTRACT_STATIC 항목의 설정에 따라서 이 두가지 항목은 문서화를 수행하거나 안 할 수 있습니다.
ex) EXTRACT_ALL = YES
EXTRACT_PRIVATE : 클래스의 모든 Private 멤버들에 대한 문서화를 할 것인가를 결정 합니다.
ex) EXTRACT_PRIVATE = YES
EXTRACT_STATIC : 소스 파일의 모든 Static 멤버들에 대한 문서화를 할 것인가를 결정 합니다.
ex) EXTRACT_STATIC = YES
SOURCE_BROWSER : 이 옵션을 YES 로 설정 하면 소스 파일의 코드리스트가 출력이 되어서 문서화 파일에서 소스 코드를 볼 수 있게 됩니다. 문서화된 객체들과 소스 코드를 교대로 참조 할 수 있는 장점이 있습니다. 소스 코드를 노출 시켜서는 안된다면 NO로 설정을 하면 되며, 모든 소스 코드를 출력하기 싫다면 VERBATIM_HEADERS 옵션도 NO로 설정해야 합니다.
ex) SOURCE_BROWSER = YES
INLINE_SOURCES : YES로 설정을 하면 함수나 클래스등의 소스등을 문서에서 직접 볼 수가 있습니다. 문서의 양이 많아지는 단점이 있기는 하지만, 여러 소스 파일에서 어떤 함수나 클래스가 호출되고 참조하는지등에 대한 흐름을 파악하기 위해서 YES 로 설정하시는것을 추천합니다.
ex) INLINE_SOURCES = YES
GENERATE_HTML : 문서화 결과를 HTML 파일로 출력 할 것인가를 결정하며 doxygen의 기본값으로 설정 되어 있습니다. HTML 문서뿐 아니라, RTF, LaTeX, Man page, PDF,XML 등의 여러 다른 포맷들로도 출력이 가능합니다. 저의 경우 처음에 몇가지 테스트를 위해서 RTF 파일과 HTML 두가지로 문서화를 하도록 테스트 해보았는데, HTML 파일로 문서화를 시킨 후에 보는 것이 보다 직관적이였습니다. 다른 포맷의 문서 생성에 대해서는 메뉴얼을 참고 하시길 바랍니다.
ex) GENERATE_HTML = YES
HTML_OUTPUT : 문서화된 HTML 파일들이 출력될 위치를 정하는 부분입니다. 이 항목은 앞서 설정한 OUTPUT_DIRECTORY 로 부터 상대 경로로 지정을 해줘야 합니다. 공백으로 둘 경우에는 “html” 디렉토리가 기본으로 생성됩니다. 저의 경우는 public_html에 출력 되도록 하였으며 보다 쉽게 접근을 위해 아파치에 가상 호스트 설정을 해놓았습니다.
ex) HTML_OUTPUT = public_html
HTML_FILE_EXTENSION : HTML 페이지의 확장자를 설정 합니다. .htm, .php, .asp등의 웹 페이지 파일 확장자를 적어주면 됩니다. 공백으로 둘경우 .html로 설정 됩니다.
ex) HTML_FILE_EXTENSION = .html
HTML_HEADER : 문서화된 결과를 좀 더 세련되게 꾸미고 싶다면 HTML 상단의 헤더 파일을 본인의 취향에 맞도록 제작후에 이부분에 적어주면 됩니다. 공백으로 둘경우에는 doxygen이 기본 header 파일을 생성합니다.
HTML_FOOTER : HTML_HEADER와 마찬가지로 HTML 하단의 푸터 파일을 제작 후 적어 줍니다.
HTML_STYLESHEET : 문서화된 HTML 파일들의 스타일 시트를 변경 할 수 있습니다. 본인의 취향에 맞는 css 파일 위치를 적습니다. 한가지 주의할 점은 doxygen은 사용자가 지정한 css 파일을 출력 디렉토리에 복사를 하기 때문에 출력 디렉토리에 css 파일을 위치 시키면 지워질 염려가 있습니다. (doxygen 출력 문서에 잘 어울리는 css 파일 구합니다. 
)
CLASS_DIAGRAMS : HTML, RTF, LaTeX 문서 포맷에서 클래스의 상속 다이어그램을 이미지로 생성시켜 줍니다. HAVE_DOT 옵션에 종속적이며 이 부분은 실제로 doxygen이 동작하는 과정에서 없어도 되는 부분입니다. 하지만 dot 툴을 설치 하시고 사용을 해보시길 바랍니다. 정말로 훌륭한 그래프들이 문서에 나타나며 이해하기에도 훨씬 쉽게 만들어 줍니다.
ex) CLASS_DIAGRAMS = YES
HAVE_DOT : 앞서 알아본 Graphviz를 설치 하였다면 이 옵션을 YES로 설정하시길 바랍니다. dot 툴은 Graphviz의 일부분으로 AT&T와 Lucent Bell 연구소에서 제작되었습니다.
HAVE_DOT 옵션과 더불어서 함께 YES로 설정을 하면 여러종류의 그래프, 다이어그램을 출력 할 수 있습니다. 프로젝트에 사용한 프로그래밍 언어에 따라서 필요한 그래프나 다이어그램이 다를 수 있습니다. 자세한 사항은 메뉴얼을 참조 하시길 바랍니다.
configuration 파일의 설정이 다 끝났다면 이제 doxygen 설정파일이름 이라고 명령을 내리시면 됩니다. 실제 문서화가 진행되는 과정을 볼 수 있습니다. 설정 파일에서 OUTPUT_DIRECTORY와 ,HTML_OUTPUT 에서 정한 디렉토리가 생성이 된 것을 알 수 있으며, 이제 브라우저로 접속하여 확인을 할 수 있습니다. 아직은 프로젝트의 소스 파일에 문서화 작업을 하지 않은 상태이기 때문에 완벽하지는 않을 것입니다. 이제 실제로 소스에 문서화를 하는 방법에 대해서 알아 보도록 하겠습니다.
Development
