Doxygen은 주석이 달린 C++ 소스 코드로부터 문서를 자동으로 생성하는 사실상 표준(de facto) 도구입니다. 그러나 C++뿐만 아니라 C, Objective-C, C#, PHP, Java, Python, IDL(Corba, Microsoft, UNO/OpenOffice 방식), Fortran, VHDL, Tcl 등 다양한 프로그래밍 언어도 폭넓게 지원합니다. 이 글에서는 우분투(Ubuntu) 환경에서 Doxygen을 설치하고 실제로 활용하는 방법을 단계별로 자세히 살펴보겠습니다.
1. Doxygen 설치하기
Doxygen을 설치하려면 터미널을 열고 다음 명령어를 입력하세요.
$ sudo apt-get install doxygen
명령어를 실행하면 아래와 같은 출력 결과가 나타나며, 진행 여부를 묻는 질문에 y를 입력하면 설치가 시작됩니다.
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages were automatically installed and are no longer required:
libterm-readkey-perl linux-headers-4.4.0-31 linux-headers-4.4.0-31-generic
linux-image-4.4.0-31-generic linux-image-extra-4.4.0-31-generic
linux-signed-image-4.4.0-31-generic
Use 'sudo apt autoremove' to remove them.
The following additional packages will be installed:
libclang1-3.6 libllvm3.6v5 libobjc-5-dev libobjc4
Suggested packages:
doxygen-latex doxygen-doc doxygen-gui graphviz
The following NEW packages will be installed:
doxygen libclang1-3.6 libllvm3.6v5 libobjc-5-dev libobjc4
0 upgraded, 5 newly installed, 0 to remove and 26 not upgraded.
Need to get 15.9 MB of archives.
After this operation, 64.0 MB of additional disk space will be used.
Do you want to continue? [Y/n] y
Get:1 https://in.archive.ubuntu.com/ubuntu xenial/main amd64 libllvm3.6v5 amd64 1:3.6.2-3ubuntu2 [8,075 kB]
Get:2 https://in.archive.ubuntu.com/ubuntu xenial-updates/main amd64 libobjc4 amd64 5.4.0-6ubuntu1~16.04.4 [111 kB]
Get:3 https://in.archive.ubuntu.com/ubuntu xenial-updates/main amd64 libobjc-5-dev amd64 5.4.0-6ubuntu1~16.04.4 [380 kB]
Get:4 https://in.archive.ubuntu.com/ubuntu xenial/main amd64 libclang1-3.6 amd64 1:3.6.2-3ubuntu2 [3,696 kB]
Get:5 https://in.archive.ubuntu.com/ubuntu xenial/main amd64 doxygen amd64 1.8.11-1 [3,679 kB]
2. Doxygen 버전 및 사용법 확인하기
설치가 완료되었다면 Doxygen에 대한 자세한 정보를 다음 명령어로 확인할 수 있습니다.
$ doxygen --help
실행 결과는 아래와 같습니다. 설정 파일 생성, 업데이트, 문서 생성 등 Doxygen의 다양한 사용 방식을 한눈에 파악할 수 있습니다.
Doxygen version 1.8.11
Copyright Dimitri van Heesch 1997-2015
You can use doxygen in a number of ways:
1) Use doxygen to generate a template configuration file:
doxygen [-s] -g [configName]
If - is used for configName doxygen will write to standard output.
2) Use doxygen to update an old configuration file:
doxygen [-s] -u [configName]
3) Use doxygen to generate documentation using an existing configuration file:
doxygen [configName]
If - is used for configName doxygen will read from standard input.
4) Use doxygen to generate a template file controlling the layout of the
generated documentation:
doxygen -l [layoutFileName.xml]
5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex.
RTF: doxygen -w rtf styleSheetFile
HTML: doxygen -w html headerFile footerFile styleSheetFile [configFile]
LaTeX: doxygen -w latex headerFile footerFile styleSheetFile [configFile]
6) Use doxygen to generate a rtf extensions file
RTF: doxygen -e rtf extensionsFile
3. 설정 파일 생성하기
소스 코드의 문서를 생성하려면 먼저 Doxygen 설정 파일을 만들어야 합니다. 다음 명령어를 실행하세요.
$ doxygen -g sample_text.conf
위 명령어를 실행하면 sample_text.conf라는 이름의 설정 파일이 생성됩니다. 이 파일에는 프로젝트 문서화에 필요한 각종 옵션들이 포함되어 있으며, 기본 구조는 아래와 같습니다.
# Doxyfile 1.8.11 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. # # All text after a double hash (##) is considered a comment and is placed in # front of the TAG it is preceding. # # All text after a single hash (#) is considered a comment and will be ignored. # The format is: # TAG = value [value, ...] # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options #---------------------------------------------------------------------------
4. 문서 생성하기
설정 파일이 준비되었다면 다음 명령어로 실제 문서를 생성할 수 있습니다.
$ doxygen sample_text.conf
명령어가 실행되면 Doxygen이 소스 디렉터리를 탐색하며 파일을 분석하고, 클래스·네임스페이스·변수 등의 목록을 구성하는 과정이 순차적으로 출력됩니다.
Searching for include files... Searching for example files... Searching for images... Searching for dot files... Searching for msc files... Searching for dia files... Searching for files to exclude Searching INPUT for files to process... Searching for files in directory /home/linux warning: source /home/linux/.dbus is not a readable file or directory... skipping. Reading and parsing tag files Parsing files Preprocessing /home/linux/abc.txt... Parsing file /home/linux/abc.txt... Preprocessing /home/linux/bbc.txt... Parsing file /home/linux/bbc.txt... Building group list... Building directory list... Building namespace list... Building file list... Building class list... Associating documentation with classes... Computing nesting relations for classes... Building example list... Searching for enumerations... Searching for documented typedefs... Searching for members imported via using declarations... Searching for included using directives... Searching for documented variables... Building interface member list...
5. 생성된 HTML 문서 확인하기
문서 생성이 완료되면 html 디렉터리 안에 웹 문서가 만들어집니다. 다음 명령어로 크롬 브라우저를 통해 결과물을 바로 확인할 수 있습니다.
$ cd html /html$ google-chrome index.html
브라우저에서 열면 아래와 같이 HTML 형식으로 정리된 API 문서를 확인할 수 있습니다.
이 글을 끝까지 따라 하셨다면 이제 우분투에서 Doxygen을 설치하고, 설정 파일을 생성한 뒤 소스 코드 문서를 만들고 확인하는 전 과정을 익히셨을 것입니다. 다음 글에서도 더욱 유용한 리눅스 팁과 트릭을 소개해 드리겠습니다. 많은 관심 부탁드립니다!