DoxyGenSetup

UserPreferences

1. 개요
2. 기본 가정
3. 설정 파일
4. 태그 파일 사용하기
5. 배치 파일

1 개요

윈도우즈 상에서 DoxyGen 커맨드 라인을 이용해 프로젝트 문서를 생성하는 과정을 다룬다.

2 기본 가정

프로젝트가 대충 아래와 같은 디렉토리 구조를 지닌다고 하자.


Project -+- Shared -+- CommonLib 
         |          | 
         |          +- NetLib 
         |  
         +- Server -+- ServerLib 
         |          | 
         |          +- GameServer 
         |          | 
         |          +- DataServer 
         | 
         +- Doc -+- CommonLib 
                 | 
                 +- NetLib 
                 | 
                 +- ServerLib 
                 | 
                 +- GameServer 
                 | 
                 +- DataServer 

Shared 디렉토리에는 두 개의 라이브러리 프로젝트가 있고, Server 디렉토리에는 1개의 라이브러리와 두 개의 실행 파일 프로젝트가 있다. 각각의 프로젝트가 의존성 관계는 다음과 같다.


• CommonLib - N/A
  
• NetLib - CommonLib 사용
  
• ServerLib - CommonLib, NetLib 사용
  
• GameServer - CommonLib, NetLib, ServerLib 사용
  
• ProxyServer - CommonLib, NetLib, ServerLib 사용
  
  
문서를 생성하고자 하는 디렉토리는 Doc 디렉토리이며, 이 디렉토리 안에 각각의 프로젝트 이름으로 디렉토리를 생성해 문서를 집어넣고자 한다.

문서 포맷은 HTML 파일 및 CHM 파일 두 가지로 한다.

CHM 파일을 생성하기 위해서는 HTML help compiler가 필요한데, 이는 Visual Studio를 설치하면 같이 설치되는 것으로 기억한다. 윈도우즈 설치하면 깔리던가? 기억이 가물가물하다. 어쨌든 기본적으로 C:\Program Files\HTML Help Workshop 디렉토리에 설치된다. 이 디렉토리 안에 hhc.exe가 있는지 확인하시라. 없다면 Microsoft에서 다운로드 받아야한다.

3 설정 파일

Doc 디렉토리 안에다 각각의 프로젝트에 대한 설정 파일을 추가한다. DoxyGen 배포폰에 딸려오는 doxywizard.exe를 사용하는 것도 괜찮다.


PROJECT_NAME           = GameServer --> 프로젝트의 이름 
PROJECT_NUMBER         = 1 
OUTPUT_DIRECTORY       = ./GameServer --> 결과물을 출력할 디렉토리 
OUTPUT_LANGUAGE        = Korean 
USE_WINDOWS_ENCODING   = YES 
BRIEF_MEMBER_DESC      = YES 
REPEAT_BRIEF           = YES 
ABBREVIATE_BRIEF       = 
ALWAYS_DETAILED_SEC    = NO 
INLINE_INHERITED_MEMB  = NO 
FULL_PATH_NAMES        = NO 
STRIP_FROM_PATH        = 
SHORT_NAMES            = NO 
JAVADOC_AUTOBRIEF      = NO 
MULTILINE_CPP_IS_BRIEF = NO 
DETAILS_AT_TOP         = NO 
INHERIT_DOCS           = YES 
DISTRIBUTE_GROUP_DOC   = YES 
TAB_SIZE               = 4 
ALIASES                = 
OPTIMIZE_OUTPUT_FOR_C  = NO 
OPTIMIZE_OUTPUT_JAVA   = NO 
SUBGROUPING            = YES 
 
EXTRACT_ALL            = YES 
EXTRACT_PRIVATE        = YES 
EXTRACT_STATIC         = YES 
EXTRACT_LOCAL_CLASSES  = YES 
HIDE_UNDOC_MEMBERS     = NO 
HIDE_UNDOC_CLASSES     = NO 
HIDE_FRIEND_COMPOUNDS  = NO 
HIDE_IN_BODY_DOCS      = NO 
INTERNAL_DOCS          = NO 
CASE_SENSE_NAMES       = YES 
HIDE_SCOPE_NAMES       = NO 
SHOW_INCLUDE_FILES     = YES 
INLINE_INFO            = YES 
SORT_MEMBER_DOCS       = YES 
SORT_BRIEF_DOCS        = NO 
SORT_BY_SCOPE_NAME     = NO 
GENERATE_TODOLIST      = YES 
GENERATE_TESTLIST      = YES 
GENERATE_BUGLIST       = YES 
GENERATE_DEPRECATEDLIST= YES 
ENABLED_SECTIONS       = 
MAX_INITIALIZER_LINES  = 30 
SHOW_USED_FILES        = YES 
#--------------------------------------------------------------------------- 
# configuration options related to warning and progress messages 
#--------------------------------------------------------------------------- 
QUIET                  = NO 
WARNINGS               = YES 
WARN_IF_UNDOCUMENTED   = YES 
WARN_IF_DOC_ERROR      = YES 
WARN_FORMAT            = "$file:$line: $text" 
WARN_LOGFILE           = GameServerWarning.log --> 경고 메시지를 기록할 파일 
#--------------------------------------------------------------------------- 
# configuration options related to the input files 
#--------------------------------------------------------------------------- 
INPUT                  = ../Server/GameServer --> 입력으로 사용할 소스 파일들이 있는 디렉토리 
FILE_PATTERNS          = 
RECURSIVE              = YES --> INPUT 필드에 준 디렉토리 하위에 있는 디렉토리들도 포함하는가의 여부 
EXCLUDE                = 
EXCLUDE_SYMLINKS       = NO 
EXCLUDE_PATTERNS       = 
EXAMPLE_PATH           = 
EXAMPLE_PATTERNS       = 
EXAMPLE_RECURSIVE      = NO 
IMAGE_PATH             = 
INPUT_FILTER           = 
FILTER_SOURCE_FILES    = NO 
#--------------------------------------------------------------------------- 
# configuration options related to source browsing 
#--------------------------------------------------------------------------- 
SOURCE_BROWSER         = NO 
INLINE_SOURCES         = NO 
STRIP_CODE_COMMENTS    = YES 
REFERENCED_BY_RELATION = YES 
REFERENCES_RELATION    = YES 
VERBATIM_HEADERS       = YES 
#--------------------------------------------------------------------------- 
# configuration options related to the alphabetical class index 
#--------------------------------------------------------------------------- 
ALPHABETICAL_INDEX     = YES 
COLS_IN_ALPHA_INDEX    = 5 
IGNORE_PREFIX          = 
#--------------------------------------------------------------------------- 
# configuration options related to the HTML output 
#--------------------------------------------------------------------------- 
GENERATE_HTML          = YES 
HTML_OUTPUT            = html 
HTML_FILE_EXTENSION    = .html 
HTML_HEADER            = 
HTML_FOOTER            = 
HTML_STYLESHEET        = 
HTML_ALIGN_MEMBERS     = YES 
GENERATE_HTMLHELP      = YES 
CHM_FILE               = index.chm 
HHC_LOCATION           = "C:\Program Files\HTML Help Workshop\hhc.exe" --> HTML help compiler의 위치 
GENERATE_CHI           = YES 
BINARY_TOC             = YES 
TOC_EXPAND             = YES 
DISABLE_INDEX          = NO 
ENUM_VALUES_PER_LINE   = 4 
GENERATE_TREEVIEW      = YES 
TREEVIEW_WIDTH         = 250 
#--------------------------------------------------------------------------- 
# configuration options related to the LaTeX output 
#--------------------------------------------------------------------------- 
GENERATE_LATEX         = NO 
LATEX_OUTPUT           = latex 
LATEX_CMD_NAME         = latex 
MAKEINDEX_CMD_NAME     = makeindex 
COMPACT_LATEX          = NO 
PAPER_TYPE             = a4wide 
EXTRA_PACKAGES         = 
LATEX_HEADER           = 
PDF_HYPERLINKS         = NO 
USE_PDFLATEX           = NO 
LATEX_BATCHMODE        = NO 
LATEX_HIDE_INDICES     = NO 
#--------------------------------------------------------------------------- 
# configuration options related to the RTF output 
#--------------------------------------------------------------------------- 
GENERATE_RTF           = NO 
RTF_OUTPUT             = rtf 
COMPACT_RTF            = NO 
RTF_HYPERLINKS         = NO 
RTF_STYLESHEET_FILE    = 
RTF_EXTENSIONS_FILE    = 
#--------------------------------------------------------------------------- 
# configuration options related to the man page output 
#--------------------------------------------------------------------------- 
GENERATE_MAN           = NO 
MAN_OUTPUT             = man 
MAN_EXTENSION          = .3 
MAN_LINKS              = NO 
#--------------------------------------------------------------------------- 
# configuration options related to the XML output 
#--------------------------------------------------------------------------- 
GENERATE_XML           = NO 
XML_OUTPUT             = xml 
XML_SCHEMA             = 
XML_DTD                = 
XML_PROGRAMLISTING     = YES 
#--------------------------------------------------------------------------- 
# configuration options for the AutoGen Definitions output 
#--------------------------------------------------------------------------- 
GENERATE_AUTOGEN_DEF   = NO 
#--------------------------------------------------------------------------- 
# configuration options related to the Perl module output 
#--------------------------------------------------------------------------- 
GENERATE_PERLMOD       = NO 
PERLMOD_LATEX          = NO 
PERLMOD_PRETTY         = YES 
PERLMOD_MAKEVAR_PREFIX = 
#--------------------------------------------------------------------------- 
# Configuration options related to the preprocessor 
#--------------------------------------------------------------------------- 
ENABLE_PREPROCESSING   = YES 
MACRO_EXPANSION        = NO 
EXPAND_ONLY_PREDEF     = NO 
SEARCH_INCLUDES        = YES 
INCLUDE_PATH           = 
INCLUDE_FILE_PATTERNS  = 
PREDEFINED             = 
EXPAND_AS_DEFINED      = 
SKIP_FUNCTION_MACROS   = YES 
#--------------------------------------------------------------------------- 
# Configuration::additions related to external references 
#--------------------------------------------------------------------------- 
TAGFILES               = CommonLib.tag=..\..\CommonLib\html \ 
                         NetLib.tag=..\..\NetLib\html 
                         ServerLib.tag=..\..\ServerLib\html --> 아래에서 설명 
GENERATE_TAGFILE       =  --> 마찬가지로 아래에서 설명 
ALLEXTERNALS           = NO 
EXTERNAL_GROUPS        = YES 
PERL_PATH              = /usr/bin/perl 
#--------------------------------------------------------------------------- 
# Configuration options related to the dot tool 
#--------------------------------------------------------------------------- 
CLASS_DIAGRAMS         = YES 
HIDE_UNDOC_RELATIONS   = YES 
HAVE_DOT               = NO 
CLASS_GRAPH            = YES 
COLLABORATION_GRAPH    = YES 
UML_LOOK               = NO 
TEMPLATE_RELATIONS     = NO 
INCLUDE_GRAPH          = YES 
INCLUDED_BY_GRAPH      = YES 
CALL_GRAPH             = NO 
GRAPHICAL_HIERARCHY    = YES 
DOT_IMAGE_FORMAT       = png 
DOT_PATH               = 
DOTFILE_DIRS           = 
MAX_DOT_GRAPH_WIDTH    = 1024 
MAX_DOT_GRAPH_HEIGHT   = 1024 
MAX_DOT_GRAPH_DEPTH    = 0 
GENERATE_LEGEND        = YES 
DOT_CLEANUP            = YES 
#--------------------------------------------------------------------------- 
# Configuration::additions related to the search engine 
#--------------------------------------------------------------------------- 
SEARCHENGINE           = NO 

4 태그 파일 사용하기

"MAIN"이라는 프로젝트가 "LIB"라는 프로젝트를 사용하는 경우, LIB 프로젝트 안에 있는 내용도 같이 문서에 포함시키기 위해서는, 태그를 사용해야 한다. INPUT 필드에 LIB 프로젝트가 존재하는 디렉토리를 적어줘도 되지만, LIB 프로젝트를 사용하는 프로젝트가 여러 개일 경우, 같은 내용을 매번 파싱하게 되므로 좋지 않다.

태그를 사용할 때 핵심이 되는 필드는 두 가지이다.


• TAGFILES : 사용할 외부 프로젝트의 태그 파일과 html 결과물의 위치를 적어준다.
  
• GENERATE_TAGFILE : 현재 프로젝트의 태그 파일을 생성하고자 할 경우, 생성할 태그 파일의 위치를 적어준다.
  
  
위의 예에서 나온 프로젝트에서는 라이브러리 프로젝트는 태그 파일을 생성하고, 실행 파일 프로젝트는 태그 파일을 생성하지 않는다.



프로젝트	태그 파일 이용 여부	태그 파일 생성 여부
CommonLib	N/A	생성
NetLib	CommonLib 태그 파일을 이용	생성
ServerLib	CommonLib, NetLib 태그 파일을 이용	생성
GameServer	CommonLib, NetLib, ServerLib 태그 파일을 사용	생성하지 않음
ProxyServer	CommonLib, NetLib, ServerLib 태그 파일을 사용	생성하지 않음


CommonLib 프로젝트 같은 경우에는 아래와 같은 태그 설정을 가진다.


TAGFILES               =  
GENERATE_TAGFILE       = CommonLib.tag 


GameServer 프로젝트 같은 경우에는 아래와 같은 태그 설정을 가진다.


TAGFILES               = CommonLib.tag=..\..\CommonLib\html \ 
                         NetLib.tag=..\..\NetLib\html 
                         ServerLib.tag=..\..\ServerLib\html 
GENERATE_TAGFILE       =   


태그 파일 이름 뒷부분의 경로는 태그 파일 이외에 태그 파일을 생성하는 데 이용한 html 문서들이 있는 디렉토리다. 주의할 것은 이 경로를 상대 경로로 줄 때, 현재 프로젝트의 html 문서들이 나오는 디렉토리를 기준으로 주어야 한다는 말이다. 즉 게임 서버의 경우, Doc/GameServer/html 디렉토리에 결과물이 생성되므로, 두 단계 위로 올라간 다음, CommonLib/html 디렉토리로 가야, html 파일들을 액세스할 수 있다.

더 자세한 것은 Linking to external documentation 문서를 참고하기 바란다.

생성한 문서에서, HTML 파일의 경우, 외부 프로젝트에 있는 클래스를 액세스하는 데 문제가 없는데, CHM 파일에서는 외부 클래스를 클릭할 경우 에러가 난다. 왜 그런 것일까?

5 배치 파일

한꺼번에 여러 프로젝트에 대한 문서를 만들기 위해서는 일괄 파일을 만드는 것이 좋다. 위의 프로젝트를 대상으로 한 일괄 파일을 한번 만들어 보자면 다음과 같다.


@echo off 
 
mkdir CommonLib 
mkdir NetLib 
mkdir ServerLib 
mkdir GameServer 
mkdir DataServer 
 
"C:\Program Files\Doxygen\bin\doxygen.exe" CommonLib.cfg 
"C:\Program Files\Doxygen\bin\doxygen.exe" NetLib.cfg 
"C:\Program Files\Doxygen\bin\doxygen.exe" ServerLib.cfg 
"C:\Program Files\Doxygen\bin\doxygen.exe" GameServer.cfg 
"C:\Program Files\Doxygen\bin\doxygen.exe" DataServer.cfg 
 
echo "로그 파일을 삭제하시겠습니까?" 
choice 
if %errorlevel% == 2 exit 
del /q *.log 

Doc 디렉토리 하위에다 일괄 파일을 둔다고 가정했다. 디렉토리 경로는 항상 주의해야 한다.

• see also DoxyGen
  

• CategoryTools